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

Simon Poole notifications at github.com
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:
https://github.com/openstreetmap/openstreetmap-website/issues/3107#issuecomment-781680313
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20210218/05705b8b/attachment.htm>


More information about the rails-dev mailing list