<p></p>
<p>Documenting APIs on the WIki (<a href="https://wiki.openstreetmap.org/wiki/API_v0.6" rel="nofollow">https://wiki.openstreetmap.org/wiki/API_v0.6</a>) has a few issues: it isn't maintained consistently, it's not considered authoritative by any means, and not easily consumable.</p>
<p>I looked at <a href="https://github.com/rswag/rswag"><code>rswag</code></a> 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.</p>
<p>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.</p>
<h4>A list of API 0.6 endpoints, as served via  <a href="http://localhost:3000/api-docs/index.html" rel="nofollow">http://localhost:3000/api-docs/index.html</a></h4>
<p><a target="_blank" rel="noopener noreferrer" href="https://user-images.githubusercontent.com/5842757/108423896-bf690d00-7238-11eb-9156-fd72064b5cb8.png"><img src="https://user-images.githubusercontent.com/5842757/108423896-bf690d00-7238-11eb-9156-fd72064b5cb8.png" alt="sw1" style="max-width:100%;"></a></p>
<h4>Testing the /api/capabilities endpoints in the browser</h4>
<p><a target="_blank" rel="noopener noreferrer" href="https://user-images.githubusercontent.com/5842757/108423981-da3b8180-7238-11eb-8873-7044cff993a0.png"><img src="https://user-images.githubusercontent.com/5842757/108423981-da3b8180-7238-11eb-8873-7044cff993a0.png" alt="sw2" style="max-width:100%;"></a></p>

<p style="font-size:small;-webkit-text-size-adjust:none;color:#666;">—<br />You are receiving this because you are subscribed to this thread.<br />Reply to this email directly, <a href="https://github.com/openstreetmap/openstreetmap-website/issues/3107">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/AAK2OLPSUMYF5BGKAQ7DZ3TS7WCWFANCNFSM4X3EHRGA">unsubscribe</a>.<img src="https://github.com/notifications/beacon/AAK2OLO4E4JUHEWRJ2JIYBDS7WCWFA5CNFSM4X3EHRGKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4MC6LPKA.gif" height="1" width="1" alt="" /></p>
<script type="application/ld+json">[
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"potentialAction": {
"@type": "ViewAction",
"target": "https://github.com/openstreetmap/openstreetmap-website/issues/3107",
"url": "https://github.com/openstreetmap/openstreetmap-website/issues/3107",
"name": "View Issue"
},
"description": "View this Issue on GitHub",
"publisher": {
"@type": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]</script>