[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