Join GitHub today
RFC0026: Adopting OpenAPI #43
As a developer on the GOV.UK registers team, it's currently a lot of work to keep the registers specification, the conformance tests, the reference implementation, and the API explorer in sync, while at the same time providing high quality reference documentation for the GOV.UK registers service. Manually updating the API reference feels like duplicated effort, especially since we already define schemas for the API in the conformance tests.
When making decisions about the tooling surrounding the reference implementation, I would prefer to automate as much as possible, and reuse existing tools rather than rolling our own.
We should also avoid building too much tooling that is coupled to our own service. In my opinion both the API explorer built into ORJ and the API reference are serving similar needs, but they have been implemented in a way that makes neither suitable for other teams who might want to host the software themselves.
Changes proposed in this pull request
This RFC proposes using OpenAPI to provide a machine readable specification of the JSON REST API. This would allow any implementor to choose existing open source tools for documentation, testing, code generation etc.
Guidance to review
If this RFC is approved, I suggest I prototype something before merging, as there are a lot of unknowns here.
Another option we could take would be to adopt OpenAPI for internal use first, without committing to providing anything indefinitely.
I think it'd be a good thing to do, and I'd like to be involved if you'll have me (at least to see what's going on under the hood).
I think Open API v3 is likely to be more feasible/easy to implement than Swagger/Open API v2. Pay has set up auto-generation of a v2 file. @kbottla or @heathd are generally very knowledgeable about it so might be able to assist with some advice if they have time.