nastra commented on pull request #3561: URL: https://github.com/apache/iceberg/pull/3561#issuecomment-976231559
> > 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. Agreed that having the pure Swagger API definition for discussion is probably the best. I was rather thinking long term and how we want to approach that. > > 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. It can be indeed easy to change the OpenAPI spec by changing/refactoring Java stuff. An approach to mitigating this would be to generate the Swagger API definition to a folder that is version-controlled and always commit that API definition as well. That way we could spot those changes. Alternatively, we could have the REST API code be generated from the Swagger definition. -- 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]
