[openstreetmap/openstreetmap-website] [💡] Documenting API using Swagger / rswag (#3107)

mmd 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...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20210218/280181da/attachment.htm>

More information about the rails-dev mailing list