API Documentation on RTD

[CThuleHansen]

The API can be annotated with swagger annotations that provide descriptions of the operations, model and similar. For example, see the picture below:

These comments are realised via

        @JsonProperty("startTime")
        final double startTime;

for the startTime model property

and

   @ApiOperation(value = "This request begins the co-simulation")
    @RequestMapping(value = "/simulate/{sessionId}", method = RequestMethod.POST, consumes = {"text/plain", "application/json"})
    public StatusModel simulate(@PathVariable String sessionId, @RequestBody SimulateRequestBody body) throws Exception 
{...}

for the simulate operation.

The serialised swagger openapi description can be accessed when webapi/Application/main is executing via: http://localhost:8082/v2/api-docs And the html version is available via: http://localhost:8082/swagger-ui.html

To begin with, we are interested in {"name":"maestro-2-simulation-controller" I am unsure if one can access the offline serialised documentation when the application is not running.

My best guess on how to integrate the api documentation on rtd is via https://pypi.org/project/sphinxcontrib-openapi/.

The docs should be integrated on this page: https://into-cps-maestro.readthedocs.io/en/latest/user/web-api.html