During some of the last weekly syncs during the DMP program, we discussed migrating the existing API documentation to use the OpenAPI Specification (OAS).
As a starting point, I’ve documented one of the create person APIs following the OAS.
Some of the primary concerns we discussed seem to be addressable:
-
We can split the
.ymlfiles and bundle them together later as a part of the build process, to avoid maintaining a giant .yml file like Zulip, which came up during our discussions. I’ve tried to demonstrate this by keeping a minimal openapi.yml which uses$refdirective to include the content fromperson.ymlthat documents the/api/v1/personendpoint, other methods likeGETcan be appended in the sameperson.ymlor whatever way we wis.h to structure it. Another pattern is reusing common components, as done here.
TL;DR: It’s easy to componentize the.ymlspec files. -
It’s quite easy to switch themes, once you have the bundled openapi.yml down. Integration with the current Hextra theme and Hugo is still something that I haven’t explored thoroughly, but it should be doable. The current UI uses ReDoc to render the documentation, we can easily use something like swagger-ui if that seems better.
The only pain point I’ve found so far, is supporting custom fields in these documentation rendering tools; they usually skip over those and making those fields render requires us to patch the rendering scripts with custom plugins.
For instance, the permissions an acting user needs isn’t something that is part of the requestBody or other recognized OAS fields, so I had to manually add an extension (as they call it) called x-permissions and describe how it should be rendered with ReDoc. I had a similar experience while trying to make it work with swagger-ui.
The plugin/hack implementation to render x-permissions in the demo project can be found here.
I don’t think it would be super common for us to write plugins for such custom extensions as the OAS tree does cover most of what we would require, and there is always the cheaper alternative of including such information in the description of the endpoint.
For comparison, this is how the create person endpoint documentation looks like with the current way of doing things.
Link
The endpoint documentation changes I introduced while working on the cht-datasource can be found here.
I think this migration would be a nice improvement towards making the API documentation consistent with most of the other tool documentations on the internet, while also helping with the maintainability and standardization side of things.
Happy to hear your thoughts!