kbendick edited a comment on pull request #3561: URL: https://github.com/apache/iceberg/pull/3561#issuecomment-975911260
> 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? In combination with JAX-RS annotations, everything that defines a REST endpoint would be combined at a single place and can be easier consumed/reasoned about by developers, rather than having the Swagger definitions and the endpoint implementations across multiple files. The `swagger.json|yaml` is then generated from the annotations, which we could then serve by a separate REST endpoint (it would basically show what you see when you upload the `swagger.yaml` to editor.swagger.io). > > Below is a quick & short example that shows how this would look like in code: > > ``` > @Path("config") > public interface ConfigurationApi { > > @GET > @Produces(MediaType.APPLICATION_JSON) > @Operation(summary = "List all catalog configuration settings") > @APIResponses({ > @APIResponse( > responseCode = "200", > description = > "All REST catalogs will be initialized by calling this route. This route\n" > + "will return at least the minimum necessary metadata to initialize the\n" > + "catalog. Optionally, it can also include server-side specific overrides.\n" > + "For example, it might also include information used to initialize this catalog\n" > + "such as the details of the Http connection pooling, etc. This route might\n" > + "also advertise information about operations that are not implemented\n" > + "so that the catalog can eagerly throw or go about another way of performing\n" > + "the desired action.", > content = > @Content( > mediaType = MediaType.APPLICATION_JSON, > schema = @Schema(implementation = IcebergConfiguration.class))), > @APIResponse(responseCode = "400", description = "Unknown Error"), > @APIResponse(responseCode = "401", description = "Invalid credentials provided"), > }) > IcebergConfiguration getConfig(); > } > ``` I looked into something like this. For the moment, I chose to go without it given that I wanted to get this presentable and wasn't exactly sure how to format existing things in this way. Also, I believe we have slightly different libraries already available for it, though I think those are coming form other modules. This week is a holiday in the US (Thanksgiving) and I'm going to ry to play around with this annotation styled AP to see if I can generate the docs in this way, though I'm not sure if we'd want to keep the annotations in the Java code or not. Thanks as always for the pointer though @nastra. Your example will help as typically I've seen this used with annotations that are more specific to Spring or some particular framework. Even for just generating the initial document, this will be helpful. -- 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: issues-unsubscr...@iceberg.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For additional commands, e-mail: issues-h...@iceberg.apache.org
