[Idea] Use Swagger to document the REST API

Development
1

Hey everybody,

I currently want to develop an openHAB binding for OctoPrint, so other people could just enter their API key and the IP address of the OctoPrint instance and have the full API available out-of-the-box.

As part of this effort I read the REST API documentation and was blown away by the quality there seeing as it's completely hand written.
This made me think it might be useful for everybody consuming the API to go one step further and make it machine readable.

So here we come to my question:
Would you accept an OpenAPI definition of the REST API, if I created one?

This would contain:

  • A list of all paths with their requirements
  • A JSON Schema to validate and document each APIs input and output
  • A test suite making sure that this document stays in sync

What this would enable API consumers to do:

What this would enable the octorprint project to do:

1 Like
2

I'd be open to that, however I'd prefer that IF that kind of effort is being done the chance is used to also look into having the OpenAPI spec being generated from the API endpoints themselves, e.g. through something like flassger and thus getting rid of the current overhead of having to keep the implementation and documentation maintained at two separate locations, instead generating the docs from the spec (sphinxcontrib-openapi or even sphinxcontrib-redoc).

The challenges there would be handling the API endpoints served through tornado though (though those admittedly are currently undocumented), and the websocket docs.

2 Likes
3

Then I'll file an issue for all of this and start preparing some PRs for it.
Thanks for guiding me into this direction.

2 Likes