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

Simon Poole notifications at
Thu Feb 18 22:34:50 UTC 2021

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. 

The later still requires significant effort regardless of the system. Given that 

- the rails port has essentially no code documentation at all
- moving the API documentation from the wiki to the rails port would put the onus on the current maintainers (but see above)
- and significantly raise the bar for contributing to it

I suspect that however well intentioned this is, it basically boils down to not documenting actual current behaviour of the API at all.

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. 

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: <>

More information about the rails-dev mailing list