Creating and maintaining APIs is no easy task — we create methods, test them, and then update them several times. Over this span of time, it’s easy to forget to update the documentation which thus makes it stale and irrelevant.

Also, many APIs are composed by an assortment of different services that have their own definition, methods, and paths. All of this combined makes the complexity of keeping a full set of documentation up-to-date extremely complex and difficult.

In this two-part series, we plan to detail how to maintain your API documentation and keep it up-to-date in Node. We will also introduce a new component recently created to assist you in this task. Throughout we’ll be using OpenAPI specification to maintain documentation in an easy way.

To achieve our goals we’ll use swagger-ui-express as a UI client and ts-openapi, a newly created Node component that allows us to declare our API schemas in Node.

As you will likely notice when getting into the code, the schemas are based on Joi types. Types.* are just wrappers to assist you, which means you can create a schema for your request parameters and use it in a validation middleware to keep your security in sync with your APIs with only minimal changes. To ensure these schemas don’t waste your time, they can also be used to validate and document your APIs.

This article (and the next) will assume you have at least some knowledge in Node and Typescript (which the examples are written in).s

Part I:

• Creating and setting up your REST server
• Giving a UI to APIs
• Advanced examples
• Applying security schemes

Part II:

• Creating a validation middleware to make your APIs rock solid
• Automating documentation generation
• Fetching different service schemas
• Combining multiple OpenAPI schemas to keep your full API spec up to date

#typescript #nodejs #documentation #open-api #node