kbendick opened a new issue #4026: URL: https://github.com/apache/iceberg/issues/4026
We don't currently have a canonical openapi document validator, so we've been relying on a combination of tools while searching for one. **TLDR** - Some of the places where we're showing more detailed spec output, we've been using `schema` components when `response` components are needed and vice verse. Namely, in some areas we drop down to a more details response body to be able to show examples that elucidate on the reasons for a route sending certain error codes. Example: This route can return 404, and we want to show that the route can return 404 because of a namespace not found or table not found or both etc. **First**. We need to fix these types so the document is fully valid. I'll introduce a PR to update the places that need changing with the minimal updates to make the document fully parse correctly. This will be the minimum change set (with one name change) to make the document more clear and fix any parsing issues. Then, I'd like to edit the document to be a bit more concise in some places (can be handled separately). **Secondly**: as for longer term validation for the REST catalog spec, we've been relying on a combination of tools such as the IntelliJ OpenAPI schema plugins, `editor.swagger.io`, and also various CLI tools for parsing it. I've yet to come across what seems like a "canonical" openapi document validator / parser. There are several tools listed on https://www.openapi.tools, and I've used a combination of `widdershins` for generating browsable markdown documents etc. That said, one of the better schema validation tools seems to be `openapi-spec-validator`. It's a nodejs / npm module that can be installed globally as a CLI tool, e.g. `npm install -g openapi-spec-validator`. First I'd like to open a PR to fix some of the minor issues. Then, if we can't find a better validation tool than `openapi-spec-validator`, we should set up a github action for validating it. The output of `openapi-spec-validator` is kind of cryptic, but it catches as many errors as `editor.swagger.io`, but gives an error response instead of a silent warning like editor.swagger.io does. I'll add some documentation on using `openapi-spec-validator` if nobody has any input on tools to use. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
