<p></p>
<p>Being the victim of absolute hopeless swagger generated documentation before (for example maproulette), it is important to note that it is just a system to semi-automatically generate good-looking documentation, not good documentation.</p>
<p>The later still requires significant effort regardless of the system. Given that</p>
<ul>
<li>the rails port has essentially no code documentation at all</li>
<li>moving the API documentation from the wiki to the rails port would put the onus on the current maintainers (but see above)</li>
<li>and significantly raise the bar for contributing to it</li>
</ul>
<p>I suspect that however well intentioned this is, it basically boils down to not documenting actual current behaviour of the API at all.</p>
<p>The other aspect is that, while a matter of contention among the maintainers and original rails-port devs, you could argue that the API should be specific implementation independent, and as a consequence as a matter of principle the documentation should be independent of any such implementation.</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#issuecomment-781680313">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/AAK2OLNNMGOIG4L2ZKLO4J3S7WIYVANCNFSM4X3EHRGA">unsubscribe</a>.<img src="https://github.com/notifications/beacon/AAK2OLPYBZTAXGYUESHB5PTS7WIYVA5CNFSM4X3EHRGKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOF2LX5OI.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#issuecomment-781680313",
"url": "https://github.com/openstreetmap/openstreetmap-website/issues/3107#issuecomment-781680313",
"name": "View Issue"
},
"description": "View this Issue on GitHub",
"publisher": {
"@type": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]</script>