Documenting REST APIs Provided by Express Applications

Home » Blog » Software » Documenting REST APIs Provided by Express Applications

swagger-jsdoc is an NPM library that allows us to generate an OpenAPI specification for REST APIs provided by an Express application.

swagger-jsdoc consumes YAML-formatted OpenAPI specification segments within JSDoc comments annotated with the @openapi annotation and turns those into a comprehensive OpenAPI specification for our API.

This specification, in turn, can for example be used for automatically having a Swagger UI documentation page created for our REST APIs (using Swagger UI Express, for instance).

While annotating Express routes with syntactically and semantically correct OpenAPI specification YAML code can admittedly be a bit tedious, I still found it the easiest approach for providing an API specification and corresponding documentation for an existing API and existing Express application code. Additionally, annotating Express routes in that manner also promotes separating route definitions from business logic (i.e. the services or functions responding to requests on those routes), which makes for a better overall application architecture.

About the author: Bjoern
Independent IT consultant, entrepreneur

Leave a Comment