Automated API implementation and documentation

In the traditional development approach, development team generally follows the below 3 steps to design API and maintain API documentation

1. Design and implement API
2. Generate Swagger file for API spec
3. Develop and maintain API documentation in Word document, include the generated Swagger file, and list out the APIs and corresponding request & response payload structure for ease of readability

One most frequently occurring issue of the above process is that the API documentation in step 3 tends to be out of date after the initial application release. At beginning the team will diligently spend time to develop the documentation, however after a while, due to tight project schedule and developers lacking time, the documentation will be out of sync with the actual APIs since every minor change may involve manual updating of the documentation.

When I worked on the recent project for implementing next generation healthcare digital platform, we adopted HL7 FHIR for the API design, we also make use of HL7 FHIR CapabiltyStatement resource to have automated way of designing API and keeping API documentation always in sync with the actual code running in the system

1. Use CapabilityStatement to define the API and request & response payload structure based on requirements
2. The CapabilityStatement will be part of the application source code. During CI/CD, the build/release pipeline will generate the corresponding Swagger file from the CapabilityStatement resource, and publish to API documentation web site
3. The API documentation web site loads and renders the newly designed APIs using RapiDoc.
4. The newly designed API will be automatically made available when the application is loaded with the updated CapabilityStatement

Below figure describes the approach we adopted to achieve the following two benefits

1. The API implemented is always in sync with the API designed
2. The API documentation is always in sync with the API implemented and running in the system.