NodeJS : Publish Swagger Specification as a package

In this article, I’m going to discuss a recommended approach to maintain a Swagger document which involves separately validating, testing and publishing it as a npm package.

Most of the people reading this article might have already come across Swagger Specification, which was a while back renamed to OpenAPI Specification.

When it comes to Swagger spec, I always recommend maintaining a separate repository.

The advantages of this approach (as explained in detail in this article) are, that the document can be -

1. Validated separately.
2. Unit-tested separately.
3. Re-used & Version controlled as a package.
4. Easily split and maintained when its size increases to maybe 5000+ lines.
5. Single source of truth avoiding multiple references, especially for large teams.

All this can be done in isolation without having to maintain the project’s and API definition’s source code in one place, which would have been a mess!

Whether you have one repo for all the projects’ API documents or one repo for each, that’s totally upto you.

Now, let’s dive into the steps.

Table Of Contents

1. Directory Structure

2. Configure npm registry