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

mmd notifications at github.com
Fri Feb 19 07:45:55 UTC 2021


> moving the API documentation from the wiki to the rails port would put the onus on the current maintainers (but see above)

Valid point, I also thought about it and came to the following conclusion: OSMF board again has [expressed](https://wiki.osmfoundation.org/wiki/Board/Minutes/2021-02-S2S/Discuss_institutionalising_budgeting_and_fund-raising_processes) their willingness to fund topics like "_Andy Allan's "room by room" renovation - API overhauling_" by having a "part-time maintainer to assist Andy Allan.". While people in this repo may find it difficult to exactly grasp what they mean by API renovation, we should definitively leverage the momentum on the API topic.

I believe getting a new paid resource up to speed by improving documentation has a number of benefits:
* Good way to get familiar with the existing Rails code base
* Clear task with no impact on existing code base (-> less effort for maintainers to review potentially breaking pull requests)
* Better documentation would improve overall developer experience

I think @gravitystorm would agree that Rails port will continue to be the center of gravity for functional requirements, database table definitions and a reference implementation, regardless of what we're doing in production.



-- 
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-781897861
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20210218/ac75a3e6/attachment-0001.htm>


More information about the rails-dev mailing list