Use swagger annotations instead of manual edits to swagger.json for OpenAPI documentation

[adamkorynta]

Component to be refactored
Refactor the manually edited OpenAPI swagger config https://github.com/opendcs/rest_api/blob/main/opendcs-rest-api/src/main/resources/swaggerui/swagger.json to use Java annotations instead.

Purpose of refactoring
Manual editing of JSON file decreases maintainability and is decoupled from the REST API Java classes where the endpoints and parameters are configured.

Proposed method
Use the swagger Java annotations: https://github.com/swagger-api/swagger-core/wiki/Annotations

Additional context
CWMS Data API uses Javalin's Swagger annotations: https://github.com/javalin/javalin-openapi

[adamkorynta]

The "servers" block also needs to figure out the parameterized context automatically. I have no investigated what mechanism can do this. This was brought up in: #64

[wjonassen]

When working on this, we need to keep this conversation in mind involving SSO and how the rest api knows where the login URL is -
https://github.com/opendcs/rest_api/pull/197/files#r1781997932

[MikeNeilson]

The "servers" block also needs to figure out the parameterized context automatically. I have no investigated what mechanism can do this. This was brought up in: #64

Javalin provides a mechanism to edit the returned openapi json/yaml before it's returned to the client. That support is rather indirect, it's just providing access to the underlying generator, so a similar mechanism should work here.

Given the nature of this API it wouldn't work to hard code it and we'll have to somehow allow the "users" to set those fields.

[MikeNeilson]

Looks like we should be able to do it the same way. https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5

I'm pretty that's what Javalin is using under the hood.

[ArthurArmour]

For reference, the OpenDCS REST API's OpenAPI documentation is currently a manually produced YAML file that requires manual updates to reflect code changes to the API endpoints, DTOs, etc.

During current work to update the OpenDCS REST API work with the CWMS Oracle database, a comparison count of the REST API’s OpenAPI manually documented end points was performed versus the actual declared endpoints and there is a mis-match between the two with some endpoints missing from the manual document (103 vs 129 in code). Additionally, there is also manual OpenAPI documentation for endpoints that do not exist, which indicates that the document could have additional errors given it was not manually kept in synch with code changes.

I approval work on this issue using funds from the F0215 Task 4 Maintenance Support task item. The manually created OpenAPI documentation can be removed and replaced with OpenAPI documentation generated through the build process via source code annotations (as is done with CDA).