The OpenAPI Initiative (OAI) was created by different industry experts who understood the value of standardizing the API descriptions. As an open API standard, the OAI is focused on creating, evolving, and promoting a vendor-neutral description format.

Whether you’re building an application or website, excellent and articulate documentation is critical to the service’s success. Developers need a clear indication of how to use the API and a way to try it. Good and well-documented API covers all of the above.

The OpenAPI Specification is an open standard that defines and documents the APIs. The OpenAPI Specification enables users to generate excellent and well-written API consumption documents. However, on the other hand, creating an OpenAPI specification takes a lot of time and effort to keep up-to-date. Often, the OpenAPI specification ends up a large, forgotten, thousand-line code & document.

To overcome this challenge and to make it as easy to document an API, IBM has launched an OpenAPI Comment Parser. The goal of OpenAPI Comment Parser is to give developers a way to generate this OpenAPI spec from the comments in line with their code. When the OpenAPI spec lives inside the code, developers are likelier to keep it up-to-date as their code changes.

This approach brings the OpenAPI spec to the code. It gets broken up into smaller, more manageable pieces. It lives next to the code that it’s describing. It enables developers to easily update the relevant spec when code changes and don’t have to go searching in the giant spec file. We are also introducing a new spec format that is tailor-made for being written in comments. On average, this new format has been shown to reduce the amount of spec needed to be written by 50 percent.

The library is built for Node.js, but the CLI can work with any language that uses this style of comments:

Create a yaml file with a base OpenAPI definition:

Add the following to your code:

Swagger UI Express is a popular module that allows you to serve OpenAPI docs from express.

There are several configuration options for parsing. For example, including and excluding certain files and paths:

To enable linting of the OpenAPI jsdoc comments, install the eslint plugin:

Using Open API Specs, user can write OpenAPI definitions in JSDoc comments or YAML files.

Each line defines specific endpoints (paths) in your API and the HTTP methods (operations) supported by these endpoints. For instance, GET /users can be described as:

Operations can have multiple parameters passed via URL path (/users/{userId}), query string (/users?role=admin), headers (X-CustomHeader: Value), or cookies (Cookie: debug=0). In addition, you can specify the parameter data types, format, whether they are necessary or optional, and other details:

For request body, use the bodyContent keyword to describe the body content and media type. Use bodyRequired to indicate that a request body is required.

Users can define possible status codes for each operation, such as 200 OK or 404 bad error, and the response body content. It allows you to define example responses for different content types as well:

The users can create different components/schemas sections to define common data structures used in the API. For example, this JSON object:

and then referenced in the request body schema and response body schema as follows:

The security schemes and security keywords are used to define the authentication methods used in your API.

Some of the supported authentication methods are given below:

• HTTP based authentication
• API key as a header or query parameter or in cookies
• OAuth 2.0
• OpenID Connect

The basis of product strategy is creating and documenting APIs while keeping an end user in mind. These are essential instruments for businesses as they go along the transformational journey, help in their IT operations, and provide developers with great experience to do a quick handshake. Royal Cyber team can assist you in developing and documenting APIs, which will actually help in achieving a bigger organizational objective. So, get in touch with our Royal Cyber experts, who can assist you in developing a winning API Product Strategy. To know more, contact us at [email protected] or visit www.royalcyber.com.