[PATCH] Improve OpenAPI and remote control output

[hiddewie]

I was using the remote control APIs and found the OpenAPI file lacking in details. Especially the types of parameters were all string which removes validation in the Swagger UI and other OpenAPI tools.

There was a TODO in the code for this.

To solve the issue of parameter typing, I added a RequestParameter class that handles the conversion and parsing from request parameters to the actual parameter value. It also contains the metadata like whether the parameter is required and the OpenAPI type.

Attached is the patch file.

Changes:

• Add response codes & descriptions to each API
• OpenAPI version from 3.0.0 to 3.0.3
• Use the configured port in the OpenAPI server block from the configured property remote.control.port or the default (using IntegerProperty).
• Add RequestParameter object that describes and parses a mandatory/optional request parameter. This information is used in the OpenAPI specification as well
• Capitalize descriptions of the request handlers

The class RequestHandler should be backwards compatible for use in plugins.

Ref ​https://swagger.io/specification/ for OpenAPI specification

[hiddewie]

patch v1

[hiddewie]

patch v2

[stoecker]

First look comments:

• New functions+classes should have an "@since xxx" so they are properly attributed during checkin
• Are the uppercase/lowercase text changes really necessary?

[hiddewie]

Added the @since on the new class and functions.

I also noticed I forgot to include RequestParameter in the patch (this is pretty difficult compared to a Git branch and a pull request). I added the missing file.

Are the uppercase/lowercase text changes really necessary?

I think they are: descriptions should be verbose pieces of text with full sentences. And those start with a capital letter. It also looks neater when the specification is opened in a Swagger UI (or similar tool).

See attached screenshots of the usage with a Swagger UI.

[hiddewie]

patch v3

[hiddewie]

Swagger UI (​https://editor.swagger.io/ for hosted version)

[hiddewie]

Single operation in swagger UI

[hiddewie]

The documentation could be improved even further by textually documenting each parameter with a description field in the OpenAPI specification.

[taylor.smock]

For RequestParameter static constructors, why have a parameter for String openapiType? Why not Class<T> classType? (I'd prefer to just use the generic class type from the rest of the static constructor, but I don't believe that is currently possible). I'd prefer to avoid Strings being passed around, since typos happen.

It looks like you have duplicated the same if condition in LoadAndZoomHandler#handleRequest (see lines with selectParameter.isPresent). The last one should probably be searchParameter instead (typos happen). This should be caught by ​AlreadyChecked, but errorprone decided to bump their minimum required Java version (8 -> 11) in the version where the AlreadyChecked detection was added. Feel free to bump the version of errorprone in your local copy, but please don't include that diff in the patch.

[taylor.smock]

@hidewie: Are you still working on the patch?

[taylor.smock]

Use classes to generate OpenAPI types