Swagger UI for REST API documentation

[kamuffe]

Is your feature request related to a problem? Please describe.

Hi.

First of all thanks a lot of your effort and the team working so great to make this project possible.
I just got OpenDTU up and running with absolutely no microcontroller knowledge ;)

In the software world when in comes to REST API there is one candidate you can't get out of scope.
Swagger UI.

Thanks a lot,
Kamuffe

Describe the solution you'd like

It is possible to integrate Swagger UI for the REST APU documentation?

See https://swagger.io/tools/swagger-ui/

This way we could also export it and import open-api.json to Postman or Insomnia or even other software to talk to OpenDTU via REST without the need manually create eachand every request.

Describe alternatives you've considered

N/A

Additional context

N/A

[CommanderRedYT]

I could think of writing the initial swagger docu, but I am not sure if I have time for maintaining it

[CommanderRedYT]

API Endpoints from Code (2991af7):

GET  /api/config/get
POST /api/config/delete
GET  /api/config/list
POST /api/config/upload

GET  /api/device/config
POST /api/device/config

GET  /api/devinfo/status

GET  /api/dtu/config
POST /api/dtu/config

GET  /api/eventlog/status

POST /api/firmware/update

GET  /api/gridprofile/status

GET  /api/inverter/list
POST /api/inverter/add
POST /api/inverter/edit
POST /api/inverter/del
POST /api/inverter/order

GET  /api/limit/status
POST /api/limit/config

POST /api/maintencance/reboot

GET  /api/mqtt/status
GET  /api/mqtt/config
POST /api/mqtt/config

GET  /api/network/status
GET  /api/network/config
POST /api/network/config

GET  /api/ntp/status
GET  /api/ntp/config
POST /api/ntp/config
GET  /api/ntp/time
POST /api/ntp/time

GET  /api/power/status
POST /api/power/config

GET  /api/prometheus/metrics

GET  /api/security/config
POST /api/security/config
GET  /api/security/authenticate

GET  /api/system/status

[CommanderRedYT]

https://github.com/tbnobody/OpenDTU/blob/master/docs/Web-API.md is missing these:

GET  /api/gridprofile/status

POST /api/inverter/order

[stefan123t]

@CommanderRedYT thanks for the overview.

I have tried to update it with the details within the current docs:
https://www.opendtu.solar/firmware/web_api/ or https://github.com/tbnobody/OpenDTU-docs/blob/master/docs/firmware/web_api.md

I found the following which was not in your list and added the two above to the list from the documentation.

GET /api/livedata/status

@tbnobody note there are two config's without a GET config, i.e. the following I found missing in both documentation and this list for Swagger UI / OpenAPI description.

GET /api/limit/config
GET /api/power/config

@kamuffe Find attached the second stab at an opendtu_openapi.yaml which I verified using the Swagger Editor against the OpenAPI v3.0.3:

opendtu_openapi.yaml

Note: Please rename from .txt to .yaml as github does not allow upload of YAML files.

[stefan123t]

Updated the Swagger OpenAPI with more examples and including OpenDTU-OnBattery API endpoints / responses.

opendtu_openapi.yaml

[CommanderRedYT]

Imo we should not include stuff in a openapi file in this repo if its not coded in this repo. onbattery is a fork. Also, it would make more sense to do a MR instead of uploading files

[stefan123t]

I would like to gather some input on the REST API and the level of detail we should detail it in ?
Eg I haven’t added any possible responses yet, only request afaIk.
Also the tags for each endpoint aint really concise yet.

@schlimmchen Regarding OpenDTU-OnBattery this would be an option which has a more extensive set of API endpoints. But removing the superfluous stuff for OnBattery from the upstream OpenDTU should be easy IMHO.
We may tag or otherwise make clear which endpoints / schema component details belong to OpenDTU-OnBattery depending on the naming convention we use.

@CommanderRedYT yes agreed but I am not easy at git using a fork/PR/gist yet and I think the Swagger OpenAPI is still too premature.
Can you check it out by downloading and renaming to opendtu_openapi.yaml or whatever you like?

I load and edit the file in the swagger editor: https://editor.swagger.io/

[stefan123t]

@CommanderRedYT where would you place the opendtu_openapi.yaml in the OpenDTU source tree ?
Do we need a special github action to build a usable Swagger API description / documentation ?

[CommanderRedYT]

@stefan123t I would propose the following:

• Not sure if in code or docs repo
• if in code repo, have it under docs/
• Mention it in the README.md (because not everyone reads the docs first)
• Mention it in the docs repo

Afaik swagger ui can just load yaml files.
But I would recommend the use of a GitHub action like this: https://github.com/marketplace/actions/swagger-ui-action

This one generates static html which we could then embed in the docs website.

[stefan123t]

@CommanderRedYT I am not good at linking this github action into the docs repo.
I am happy that the PR #2410 worked out fine and hope that @tbnobody finds this useful.

@schlimmchen you may use the larger opendtu-onbattery_swagger_openapi.yaml which I added earlier.

[CommanderRedYT]

@stefan123t I will try implementing it when I have time