rdblue commented on pull request #3561: URL: https://github.com/apache/iceberg/pull/3561#issuecomment-975833631
> Have you thought about/considered something like https://github.com/eclipse/microprofile-open-api (just an example, but there are other libs available as well), which allows you to add OpenAPI annotations directly to your Java code, so that the OpenAPI spec+docs and the code are all at one place? Right now, the main thing is to have something to discuss, and being able to paste this file into the swagger UI makes it really easy to discuss the API. Longer term, I'm not sure what the best path will be to maintain the API definition, but I'm really reluctant to publish whatever happens to be in the Java implementation through annotations. While that's an easy way to keep the code and the definition in sync, it is probably not a great way to manage a specification that is portable. It's too easy to refactor Java and make unintended changes to the OpenAPI spec, right? Maybe I'm wrong here, but it seems easy to mess up the API that way. -- 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]
