Swagger UI for REST API documentation

kamuffe commented 2 years ago

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 commented 1 year ago

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

CommanderRedYT commented 1 year ago

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 commented 1 year ago

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

GET  /api/gridprofile/status

POST /api/inverter/order

stefan123t commented 4 months ago

@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 commented 4 months ago

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

opendtu_openapi.yaml

CommanderRedYT commented 4 months ago

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 commented 4 months ago

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 commented 2 weeks ago

@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 commented 2 weeks ago

@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 commented 2 weeks ago

@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 commented 1 week ago

@stefan123t I will try implementing it when I have time

tbnobody / OpenDTU