Adding static API docs to my tiny API
In my first story in a series, I explained that I spend about a day a week solving problems that interest me with tiny software applications. I’ve been assembling a tool-kit to quickly build against architectural patterns that I find keep coming up in tiny apps.
In a later story I explained my stack for building tiny APIs. I make use of Open API — the open standard for defining API contracts that started life as Swagger. Swagger provide a beautiful online editor for messing around with specs in-browser. I import the Open API definition to generate my AWS Gateway configuration in a CI/CD pipelines, and I import them into Postman for testing. I use Github Actions to do the heavy lifting of creating API Gateway configurations and building and deploying Node.js code to GCP Firebase Functions.
Improving the developer experience
The Open API specs are handy, and its great being able to import them into Postman, but I really like to have a good old-fashioned API docs page that explains the purpose of the parameters and the meaning of error status codes. The content for that documentation is in my Open API spec, but I wanted a way to make sure the docs were rendered to hosted static HTML and updated whenever the API is modified.
Swagger provide a tool called Swagger UI that can do the HTML site generation from a spec, but to support CI/CD I turned, as usual, to Github Actions. The community hasn’t failed me yet, and this time I found this action that only needs a spec and and the name for an output directory and boom — static API docs generation. Putting that together with my usual Github Actions for S3 deployment and Cloudfront cache invalidation, and a few minutes later I had an automatically updating API doc site:
jobs:
deploy:
name: Deploy
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@master
- name: Generate Swagger UI
uses: Legion2/swagger-ui-action@v1
with:
output: swagger-ui
spec-file: nz-recycling-advanced-prod-oas30-apigateway.json
- name: Deploy to S3
uses: jakejarvis/s3-sync-action@master
with:
args: --acl public-read --delete
env:
AWS_S3_BUCKET: www.cronin.nz
DEST_DIR: apps/recycling-api-docs
SOURCE_DIR: swagger-ui
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
AWS_REGION: us-west-2
- name: Invalidate Cloudfront cache
uses: muratiger/invalidate-cloudfront-and-wait-for-completion-action@master
env:
DISTRIBUTION_ID: ${{ secrets.AWS_DISTRO }}
PATHS: '/*'
AWS_REGION: us-west-2
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
