[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

![sw1](https://user-images.githubusercontent.com/5842757/108423896-bf690d00-7238-11eb-9156-fd72064b5cb8.png)


#### Testing the /api/capabilities endpoints in the browser


![sw2](https://user-images.githubusercontent.com/5842757/108423981-da3b8180-7238-11eb-8873-7044cff993a0.png)


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/3107
-------------- 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