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: https://github.com/opendcs/rest_api/pull/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.