![\"Node](\"https:\/\/blog.logrocket.com\/wp-content\/uploads\/2023\/04\/node-js-open-api-spec.png\")
\nIf you\u2019ve ever done an API integration, you\u2019d know it. Whenever something breaks or doesn\u2019t work, an API owner needs to communicate a bunch of basic details, including status codes, happy paths, required parameters, and authentication mechanisms.<\/p>\n
This approach requires a constant context switch and is clearly not productive. Here, the OpenAPI Specification<\/a> can help; you might already have it, but is it scalable? In this article, we\u2019ll learn how to create an OpenAPI Specification document that is readable, scalable, and follows the principle of extension without modifying the existing document.<\/p>\n We\u2019ll use a sample Node.js API<\/a> that uses the Express framework. We\u2019ll write the specification document for this API and learn how to create a scalable and easy-to-maintain OpenAPI specification along the way. Let\u2019s get started!<\/p>\n Jump ahead:<\/em><\/p>\n When it comes to working with any API, we all know how important having a well-written documentation is. An incomplete, or worse, incorrect documentation results in wasted time and effort.<\/p>\n The OpenAPI Specification aims to solve this problem by providing a standard, language-agnostic interface to understand and interact with the API in a way that is easier for both humans and computers.<\/p>\n An OpenAPI specification document describes the complete API in an industry-standard manner. It is battle-tested, meaning you won\u2019t miss out on any useful information.<\/p>\n In a world where we\u2019re constantly working on the next big thing, it\u2019s pretty boring to spend time writing documentation. However, having detailed written documentation can benefit the rest of your team as well as any end users. Writing scales, and anyone can refer to the documentation and understand the API from the inside-out.<\/p>\n This alone is enough motivation to incorporate an OpenAPI specification in your APIs. But, the benefits don\u2019t stop there. For one, by providing the specification, you can generate API code in any language, which helps in quick prototyping if you want to replicate any API using a different programming language.<\/p>\n In addition, because the specification is aware of all the possible request parameters and corresponding responses, you can use it to generate test cases for your API and make sure your API is working as expected.<\/p>\n An OpenAPI specification consists of several different components, each having a dedicated and important purpose. Let\u2019s take a look at each one.<\/p>\n The The The The Schemas help you define the data type of A schema object can be understood as a variable in your Node.js application. Both promote reusability but aren\u2019t involved unless used in the code.<\/p>\n The The The Now that we have the basic understanding of the OpenAPI Specification, why it is important, and what components comprise it, let\u2019s document our sample Node.js API.<\/p>\n It\u2019s very important to make sure that the specification is scalable. Putting everything inside of a single file defeats the purpose of human readability, but unfortunately, it is a common practice.<\/p>\n We\u2019ll create a better, more human-readable specification that achieves all of the things it promises. Before we get to it, let\u2019s make sure to create a Once it\u2019s done, we can install the required dependencies.<\/p>\n We\u2019ll need two packages to create a scalable OpenAPI specification; run the following command to install them:<\/p>\n We need to create schemas for the common and reusable entities in our REST API. Since we only have one major entity, we\u2019ll create a schema for There are three possible responses that our API will return to the clients:<\/p>\n Keeping our API\u2019s behavior in mind, we\u2019ll create three response files documenting these scenarios.<\/p>\n For a successful API response, we\u2019ll use the code below:<\/p>\n While your API serves a request, issues can occur. For example, the database connection might time out, the network connection can get lost, your API might over-utilize resources like CPU, RAM, etc., causing a shutdown.<\/p>\n Whenever our API fails to serve the request, by no fault of the client, we return an internal server error response, a 500 HTTP status. Below is our specification document for such an error:<\/p>\n And, finally, we give a bad request response to the client if it passes invalid or incompatible details that break our API contract:<\/p>\n The sample API doesn\u2019t enforce any form of authentication. That\u2019s not our goal; the goal is to understand how to write the specification, which can handle authentication. To solve this issue, we\u2019ll require an authentication header with a bearer token scheme and apply it globally.<\/p>\n Below is our security schema:<\/p>\n You can make authentication mandatory by adding it to the root of your OpenAPI specification document:<\/p>\n Finally, add the following scripts in the To generate the final OpenAPI specification file, simply run the following command:<\/p>\n To validate your specification for syntactical correctness, run the code below:<\/p>\n You can even choose to combine the validation and specification generation commands to automatically validate the specification every time you generate one:<\/p>\n You can also automate the OpenAPI specification generation by adding the Why wouldn\u2019t any automation enthusiast do this? I\u2019ve already added this to the sample Node.js API, so you can clone the project and play around with it.<\/p>\n With that, we\u2019ve finished writing our OpenAPI Specification, and it looks clean. There are certain practices that we should follow to increase the quality of our specification and ensure that it\u2019s scalable.<\/p>\n When writing schemas, responses, or any other component of the specification, you should avoid adding unnecessary context that complicates the name. For example, using When creating response components for your OpenAPI Specification, you should try to make the responses as generalized as possible as long as it doesn\u2019t contradict the way your API is written. This promotes reusability and makes your specification scalable.<\/p>\n You can use the specification file and share it with other teams during integration requirements. Swagger UI makes the specification interactive<\/a>, so it\u2019s easier to consume and understand.<\/p>\n\n
What is the OpenAPI Specification?<\/h2>\n
Why write an OpenAPI specification?<\/h2>\n
What does an OpenAPI specification look like?<\/h2>\n
info<\/code><\/h3>\ninfo<\/code> object provides metadata about the API, like its title, version, and contact information. You can use this information to identify the API and understand its purpose.<\/p>\nserver<\/code><\/h3>\nserver<\/code> object describes the URLs of the API, including the base URL as well as any variables that are used in the URL.<\/p>\npaths<\/code><\/h3>\npaths<\/code> object describes the endpoints of the API and the operations that can be performed on them. This includes the HTTP methods, like GET<\/code>, POST<\/code>, and PUT<\/code><\/a>, as well as the parameters and responses for each endpoint.<\/p>\ncomponents<\/code><\/h3>\ncomponents<\/code> object is a container for reusable objects like schemas, examples, and security schemes. You can reference these objects from elsewhere in the specification, making it easier to maintain and update the specification.<\/p>\nSchemas<\/h3>\n
input<\/code> and output<\/code> objects. Any request parameter, request body, or response object that you use in the specification can be abstracted as a schema object and reused wherever required.<\/p>\nresponses<\/code><\/h3>\nresponses<\/code> object contains all the possible API responses mapped to the HTTP status code.<\/p>\nsecurity<\/code><\/h3>\nsecurity<\/code> object describes the security requirements for the API, including the types of authentication and authorization that are supported, as well as the scopes that are required for different operations.<\/p>\ntags<\/code><\/h3>\ntags<\/code> object describes a list of tags used by the specification with additional metadata. This can be used to group related endpoints together and organize the specification.<\/p>\nWriting a specification for our sample Node.js API<\/h2>\n
docs\/<\/code> folder at the root of the project. The folder structure looks like the following:<\/p>\n|- docs\/\n|----schemas\/\n|----responses\/\n|----paths\/\n|----index.json\n|- src\/\n|- package.json\n|- package-lock.json\n<\/pre>\n
Installing dependencies<\/h3>\n
npm install @apidevtools\/swagger-cli\n<\/pre>\n
Creating a schema<\/h3>\n
Item<\/code> in docs\/schemas\/item.json<\/code>:<\/p>\n{\n \"type\": \"object\",\n \"required\": [\"name\", \"hash\", \"rating\", \"price\"],\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"rating\": {\n \"type\": \"string\",\n \"example\": \"4\"\n },\n \"price\": {\n \"type\": \"number\"\n },\n \"hash\": {\n \"type\": \"string\"\n }\n }\n}\n<\/pre>\nWriting possible responses<\/h2>\n
\n
200<\/code>: Success<\/li>\n500<\/code>: Internal server error<\/li>\n400<\/code>: Bad request<\/li>\n<\/ol>\nSuccessful response<\/h3>\n
{\n \"description\": \"Response for operation successful\",\n \"content\": {\n \"application\/json\": {\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"boolean\",\n \"enum\": [true],\n \"example\": true\n },\n \"item\": {\n \"$ref\": \"..\/schemas\/item.json\"\n }\n }\n }\n }\n } \n}\n<\/pre>\nInternal server error<\/h3>\n
{\n \"description\": \"Response for operation successful\",\n \"content\": {\n \"application\/json\": {\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"example\": \"Something went wrong while creating a new item!\"\n },\n \"item\": {\n \"type\": \"object\",\n \"enum\": [null]\n }\n }\n }\n }\n } \n}\n<\/pre>\nBad request<\/h3>\n
{\n \"description\": \"Response for operation successful\",\n \"content\": {\n \"application\/json\": {\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"example\": \"Something went wrong while creating a new item!\"\n },\n \"item\": {\n \"type\": \"object\",\n \"enum\": [null]\n }\n }\n }\n }\n } \n}\n<\/pre>\nAdding security schema<\/h3>\n
{\n \"bearerAuth\": {\n \"type\": \"http\",\n \"description\": \"JWT authorization header using the bearer scheme\",\n \"scheme\": \"bearer\",\n \"bearerFormat\": \"JWT\"\n }\n}\n<\/pre>\n\"security\": [\n {\n \"bearerAuth\": []\n }\n ]\n<\/pre>\nPutting it all together in the paths section<\/h3>\n
package.json<\/code> file:<\/p>\n\"scripts\": {\n \"docs:debug\": \"swagger-cli validate -d docs\/index.json\",\n \"docs:generate\": \"swagger-cli bundle docs\/index.json --outfile openapi.json\",\n}\n<\/pre>\nnpm run docs:generate\n<\/pre>\n
npm run docs:debug\n<\/pre>\n
\"scripts\": {\n \"docs:debug\": \"swagger-cli validate -d docs\/index.json\",\n \"docs:generate\": \"npm run docs:debug && swagger-cli bundle docs\/index.json --outfile openapi.json\",\n}\n<\/pre>\ndocs:generate<\/code> script above to your Husky pre-commit hook<\/a>. Therefore, you\u2019ll always have a valid and up-to-date specification on every commit:<\/p>\n\"husky\": {\n \"hooks\": {\n \"commit-msg\": \"commitlint -E HUSKY_GIT_PARAMS\",\n \"pre-commit\": \"npm run docs:generate && npm run codefix && git add .\"\n }\n }\n<\/pre>\nBest practices for writing an OpenAPI specification<\/h2>\n
Don\u2019t add redundant context in names<\/h3>\n
response\/success.json<\/code> is much more concise and readable than response\/successResponseFromHTTPRequest.json<\/code>.<\/p>\nChoose generic responses whenever possible<\/h3>\n
Visualizing the specification with Swagger UI<\/h2>\n
![\"Visit](\"https:\/\/blog.logrocket.com\/wp-content\/uploads\/2023\/04\/visit-node-js-api-sample-url-open-api-spec.png\")
<\/p>\n