Documenting API using Swagger / rswag

[mmd-osm]

Documenting APIs on the WIki (https://wiki.openstreetmap.org/wiki/API_v0.6) has a few issues: it isn't maintained consistently, it's not considered authoritative by any means, and not easily consumable.

I looked at rswag 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.

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.

A list of API 0.6 endpoints, as served via http://localhost:3000/api-docs/index.html

Testing the /api/capabilities endpoints in the browser

[simonpoole]

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.

[tomhughes]

Yes I'm not convinced about the wisdom of documenting the API in this repository when most of it (at least as used in production) isn't actually implemented here.

[mmd-osm]

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 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 grasp what exactly they mean by API overhauling, 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.

[gravitystorm]

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.

Yep, I would agree with that whole-heartedly. I also have plans to make this codebase (slightly) more performant, which will reduce the need for some deployments to add cgimap. So even if OSMF don't use some of the API calls in production, other installations will continue to do so.

"part-time maintainer to assist Andy Allan."

Thanks for pointing this out; I haven't been involved in any of the discussions but I suspect this has been more focussed on OSMF budget opportunities rather than actually progressing it yet.

The later still requires significant effort regardless of the system.

@simonpoole I'm not familiar with swagger or the maproulette documentation. Could you give some idea here as to what else would be involved? Is it inline controller method documentation, or more, or something else? Do you have any links to good/bad examples?

I'm quite happy to have the documentation here in the repo, preferably near the code but I'd rather it was under source control than in a free-for-all.

Testing the /api/capabilities endpoints in the browser

@mmd-osm Is it just get requests that can be tested? I'm concerned because other systems I'm more familiar with that allow online testing like this either have a 'test mode' API, or it's only your own account that you can mess up by playing around while logged in. On the flip side, if all you can test are get requests, it becomes a bit less interesting! Do you have any details on this?

[mmd-osm]

Is it just get requests that can be tested? I'm concerned because other systems I'm more familiar with that allow online testing like this either have a 'test mode' API, or it's only your own account that you can mess up by playing around while logged in. On the flip side, if all you can test are get requests, it becomes a bit less interesting! Do you have any details on this?

You can spin up a Swagger Petstore test frontend at https://editor.swagger.io/ and try out common HTTP verbs (GET, POST, PUT, PATCH, DELETE, ...) + authorization to get some idea how this works. For testing purposes, a few endpoints could be included, such as http://localhost:3000 and https://master.apis.dev.openstreetmap.org/. Users can then try things out using their own credentials.