nastra commented on pull request #3561: URL: https://github.com/apache/iceberg/pull/3561#issuecomment-975539916
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, examples = {@ExampleObject(ref = "configurationExample")}, schema = @Schema(implementation = IcebergConfiguration.class))), @APIResponse(responseCode = "400", description = "Unknown Error"), @APIResponse(responseCode = "401", description = "Invalid credentials provided"), }) IcebergConfiguration getConfig(); } ``` -- 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]
