Documenting an ExpressJs API
With the requirement of a new project and it being the end of the year and things slowing down, I decided to learn something new.
Having worked on a project for a fair amount of time that has been written in Typescript, I decided to use that as my language of choice, I also wanted to use AWS ApiGateway and Lambda to serve up my API.
ApiGateway has had some interesting changes this year at re:invent; they added a new type of API (an HTTP API) and the costing is estimated to be about 70% cheaper than REST at this point, the only down side for me is that the only Auth method is JWT, and I will be needing API Keys and Rate Limiting.
For starters, my packages of choice will be:
- serverless (packaging and uploading to aws lambda and api gateway)
- ExpressJS (webserver)
- aws-serverless-express (aws lambda proxy for express)
- swagger-jsdoc (JsDoc exports that output to a swagger.json file)
- swagger-ui-express (Swagger UI for testing)
- ReDoc (UI for documentation)
Both ReDoc and swagger-jsdoc have a cli, but I will be using this later on.
You might be wondering about why I am using serverless for this - because I am using express as well, if you omit all the boilerplate code for getting Express running on Serverless you can pretty much deploy this on any server as an express app using docker.
Here is my tsconfig.json:
What I found is that “esModuleInterop”: true is required for typescript to do imports without using the * as and the get module = imports to work correctly. I am also using es2019 because arrays now have a flatMap method which will come in handy later.
My folder structure looks something like this:
- [Root API Folder]
- src
- app.ts
- handler.ts
- swagger.yaml
- swaggerSpec.js
- routes
- v1
- [pluralized element]
- index.ts
So I have a few things going on here:
- handler.ts is used for bootstrapping my lambda function to fire
- app.ts controls all my base routes for express and bootstraps my express app
- swagger.yaml has my definition of my api
- swaggerSpec.js is the specification that I need to pass through to swagger-jsdoc. My biggest frustration was embedding a js file in here and duplicating some of my code, but according to the docs the Spec file has to be in a specific format and the CLI does not like ts files!
Please note that you will also need to either globally install or use npx for the ReDoc and swagger-jsdoc CLIs.
Time for some swagger.
What my swaggerSpec.js does is it loads my swagger.yaml file in and exports it along with the other parameters required by the CLI for swagger-jsdoc.
And here is an example swagger.yaml. I liked the fact that using the yaml file made it much easier for a multiline description, as well as the ease at which I could use openapi version 3+, which meant I would now use the components section for definition securitySchemes as well as Schemas that I could then $ref across my documentation.
To generate your swagger.json file, run the command below in the root of your project, this also makes it easier to run it in a CI/CD environment:
npx swagger-jsdoc -d src/swaggerSpec.jNow for the Redoc bit which will generate a redoc-static.html file and can be deployed anywhere (in my case this would be AWS):
npx redoc-cli bundle swagger.jsonI then proceeded to put all of this in my package.json under scripts where I could just run yarn docs:build and get both files outputted and ready for deployment:
With the current setup there is no actual api documentation yet, so lets add some docs. I add this file to my project src/routes/v1/pets/index.js:
Next, run yarn docs:build and you should have Redoc outputting your static documentation which you can then open in your favourite internet browser.
I did add a few additional routes to express for testing during development, which might help out with debugging.
I am using pug to render an html file which has the CDN version of ReDoc:
The pug file is placed under [project root]/views/index.pug
I hope this helps someone else out there getting their API documented and the documentation hosted.
