HonahX commented on code in PR #906: URL: https://github.com/apache/polaris/pull/906#discussion_r1936132542
########## spec/README.md: ########## @@ -0,0 +1,29 @@ +# Polaris API Specifications +Polaris provides two sets of OpenAPI specifications: +- `polaris-management-service.yml` - Defines the management APIs for using Polaris to create and manage Iceberg catalogs and their principals +- `polaris-catalog-service.yaml` - Defines the specification for the Polaris Catalog API, which encompasses both the Iceberg REST Catalog API + and Polaris-native API. + - `polaris-apis` - Contains the specifications of Polaris-native API + - `rest-catalog-open-api.yaml` - Contains the specification for Iceberg Rest Catalog API + +## Generated Specification Files +The specification files in the generated folder are automatically created using OpenAPI bundling tools such as +[Redocly CLI](https://github.com/Redocly/redocly-cli). + +These files should not be manually edited (except adding license header). They are intended for preview purposes only, +such as rendering a preview on a website. + +Whenever the source specification files are updated, the generated files must be re-generated to reflect those changes. + +Below are steps to generate `bundled-polaris-catalog-service.yaml` Review Comment: Yeah, it is a weird but it is necessary for Polaris's hugo site to render preview. https://github.com/apache/polaris/blob/main/site/content/in-dev/unreleased/rest-catalog-open-api.md?plain=1#L27 https://github.com/apache/polaris/blob/569bf02dbf07ff553c6f22c36093c0ca3230dff7/site/layouts/shortcodes/redoc-polaris.html#L39 The site need a url of the yaml to render the preview: https://polaris.apache.org/in-dev/unreleased/rest-catalog-open-api/, so we have to push it to the github We can remove the generated one from github if our site can render a local yaml, but that to my current understanding will require non-trivial change to our site so we may explore later. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
