DEV Community

Cover image for OpenAPI Specification: The Complete Guide

Posted on

OpenAPI Specification: The Complete Guide

I wrote an Introduction on OAS in my previous article, you should read it before continue.
Before explain into how to generate an OAS, I think it is important to highlight the importance of OAS.

Why Use OAS ?

An OAS (Other acronym sh**t 😂) is a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. An OpenAPI Specification document always starts with "openapi": followed by the version of the Specification it is using.

The benefits of using an OpenAPI Specification include:

  1. Time consuming: OpenAPI Specification can help reduce the amount of time spent on documentation by automating the process.

  2. Language-agnostic: An OpenAPI Specification is written in YAML or JSON and is completely language-agnostic. This means that any language can be used to write an OpenAPI Specification document.

  3. -The ability to validate your API: An OpenAPI Specification document is meant to be read by both humans and computers. This means that the document can be used by tools to automate processes for example validate your API , or even code generation.

  4. Comprehensive: Specification can help improve the quality of documentation by providing a standard way to describe APIs. In addition the specification should include everything that is necessary to describe the API. This includes the URL of the API, the methods supported by the API, the parameters that can be passed to the API, and the response format of the API.

  5. Public: Anyone who wishes to utilize an OpenAPI Specification document should be able to do so.
    This indicates that the document should be freely available to anybody who wishes to utilize it.

Listing the tools to generate..

The following is a list of libraries and tools that can help you create an OpenAPI Specification (OAS) document for your current REST API application, organized by implementation technology.


  • swag automatically generates RESTful API documentation with Swagger 2.0 - GitHub - swaggo/swag
  • go-swagger brings to the go community a complete suite of fully-featured, high-performance, API components to work with a Swagger API: - Github - Swagger 2.0 implementation for go



  • wagger-php is a php swagger annotation and parsing library which generates interactive OpenAPI documentation for your RESTful API using doctrine annotations. - GitHub - zircote/swagger-php


  • swagger-autogen performs the automatic construction of the Swagger documentation - swagger-autogen - npm

  • NestJS provides a dedicated module which allows generating OpenAPI (Swagger) - Github - nestjs/swagger

  • swagger-express is a solution to integrate swagger with express - swagger-express - npm

  • express-oas-generator generate OpenAPI (Swagger) specification for existing ExpressJS 4.x REST API applications - express-oas-generator - npm

  • hapi-swagger is a OpenAPI (aka Swagger) plug-in for Hapi When installed it will self document the API interface in a project - hapi-swagger - npm





Testing and Testing!

There has been an explosion of accessible technology since the introduction of cloud computing around a decade ago.
Developers working hard to improve, cool, or smooth things.
It's challenging to keep track of tools as they evolve and new ones emerge.
Furthermore, because adopting new tools takes time, it is critical to assess new technologies for use. It is the same in the API design environment.
Imagine having an online tool that generates a comprehensive real-time endpoints map and guides you along using a params table. Wouldn’t that be sweet?

BLSTs solution for API development is very a game changer.
We just released it today for the fist time!
Visit, upload your OpenAPI file, and check out the results.

A picture is always better than a thousand words.

Image description

Visit our Open-source repo.
Contribute, like it and use it ;)

Join us on discord .

Top comments (1)

chaimpeer profile image
Chaim Peer

Implementing a new system by properly understanding documentation, this OAS scan may be best way to solve this case!