Our API is documented using OpenAPI. You can view the documentation at https://api.publish-teacher-training-courses.service.gov.uk/api-docs. We use a few gems to write specs for the API which are then used to generate the documentation. The specs can be found in /spec/docs.
We use Tech Docs to build documentation. To update documentation, run the command below which will generate an open api specification file. The docker build will then take these files to generate the static site.
-
If we want to change the documentation, go to
swagger/public_vxand make changes to the yml files. -
Run the swaggerize command to generate a new api_spec.json
Use the following command to generate OpenAPI specification:
bundle exec rake rswag:specs:swaggerize- We build the documentation in a separate container to the main app and copy the contents into the main image.
bin/build-docsThis will:
- build a container only of the docs
- copy the built docs to
public/docs - allow you to visit
http://publish.localhost:3001/docs/and see your changes
http://publish.localhost:3001/api-docs/public_v1/api_spec.json