2023-01-30
Accepted
The OpenAPI specification is a standard for describing REST APIs and Swagger UI is used to visualise and interact with a specification file in more user-friendly manner. These are used widely used within HMPPS to document APIs, e.g. Prison API's OpenAPI specification and Prison API's Swagger UI. This is achieved by using the SpringDoc OpenAPI library and annotating the codebase which the library then uses to expose two endpoints: one for the OpenAPI specification in JSON format and another for Swagger UI.
In ministryofjustice/hmpps-integration-api#19, we followed precedence and added OpenAPI annotations to our codebase. However, in ministryofjustice/hmpps-integration-api-docs#11 we decided to change our approach to manually managing a OpenAPI specification file and using the feature of the tech docs template to convert the file into documentation. This approach presents us with a number of benefits over the annotation method:
- Codebase is not polluted with lots of annotations.
- Code for endpoints do not have to exist in order for them to be documented. This means that we can define endpoints that will exist and provide documentation as early as possible to future consumers like a contract and provides them with the option to create a simulator based on the file. Furthermore, we can use it as part of feature development of API endpoints, akin to a design prototype - Documentation Driven Development.
- GOV.UK/Ministry of Justice style - with annotations we are stuck with the Swagger UI style.
- Content is all in one place and we can be flexible with it i.e. add sections around auth, architecture, ADRs, release notes, rate limiting etc. more easily.
- We will manually manage our OpenAPI specification file instead of using annotations in our codebase to generate one.
- Our OpenAPI specification will be used to automatically generate documentation.
- We will remove OpenAPI annotations in our codebase.