[openstreetmap/openstreetmap-website] [💡] Documenting API using Swagger / rswag (#3107)
notifications at github.com
Thu Feb 18 21:42:58 UTC 2021
Documenting APIs on the WIki (https://wiki.openstreetmap.org/wiki/API_v0.6) has a few issues: it isn't maintained consistently, it's not considered authoritative by any means, and not easily consumable.
I looked at [`rswag`](https://github.com/rswag/rswag) as a way to include API documentation right inside this repo, along with a nice UI to test endpoints and a much easier way for API consumers to generate their own code based on the OAS3 spec that comes along with it.
I'm just posting a few screenshots how this could look like. It's mostly auto-generated content that can be enhanced by additional details/descriptions/error status code lists/examples, etc. Maybe this is even good enough to get rid of the Wiki page altogether and direct developers to the swagger docs instead.
#### A list of API 0.6 endpoints, as served via http://localhost:3000/api-docs/index.html
#### Testing the /api/capabilities endpoints in the browser
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the rails-dev