How to Generate OpenAPI (OAS) Specs for REST APIs

The OpenAPI Specification (OAS) defines 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.[1]

APISec supports 1.0, 2.0, 3.x versions of the OpenAPI specification (OAS) as well as Postman and RAML formats.

The following is a list of some libraries and resources which can be helpful in generating an OpenAPI Specification (OAS) document for your existing REST API application grouped by implementation technology.

ASP.NET Core

• The two main OpenAPI implementations for .NET are Swashbuckle and NSwag. They are explained nicely in the Microsoft ASP.NET documentation - ASP.NET Core web API documentation with Swagger / OpenAPI | Microsoft Docs
• The OpenAPI.NET SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model - GitHub - microsoft/OpenAPI.NET

Spring

• Springfox supports automated JSON API documentation for API's built with Spring - GitHub - springfox/springfox
• The springdoc-openapi Java library helps automating the generation of API documentation using Spring Boot projects - GitHub - springdoc/springdoc-openapi

Java

• For JAX-RS based projects(Jersey/RESTEasy/Mule), Swagger Core provides examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API - GitHub - swagger-api/swagger-core
• The Swagger Maven Plugin is a JAX-RS & SpringMVC supported maven build plugin, helps you generate Swagger JSON and API document in build phase -  GitHub - kongchen/swagger-maven-plugin

Python

• Flask-RESTX is an extension for Flask which provides a coherent collection of decorators and tools to describe your API and expose its documentation properly using Swagger - GitHub - python-restx/flask-restx
• Falcon-apispec is an apispec plugin that generates OpenAPI specification (aka Swagger) for Falcon web applications -  Github - alysivji/falcon-apispec
• drf-yasg - Yet another Swagger generator helps in automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code. - GitHub - axnsan12/drf-yasg
• drf-spectacular is a sane and flexible OpenAPI 3 schema generation for Django REST framework - GitHub - tfranzel/drf-spectacular 

Node.js

• 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 simple and clean solution to integrate swagger with Express - swagger-express - npm
• express-oas-generator automatically generates 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

PHP

• swagger-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

Ruby

• rspec-openapi generates OpenAPI schema from RSpec request specs - Github - rspec-openapi  
• rswag seamlessly adds a Swagger to Rails-based APIs - Github - rswag 
• zero-rails_openapi is a concise DSL for generating OpenAPI Specification 3 (OAS3) JSON documentation for Ruby application - GitHub - zhandao/zero-rails_openapi
• The grape-swagger gem provides an auto generated documentation for your Grape API - GitHub - ruby-grape/grape-swagger
• Swagger::Blocks is a DSL for pure Ruby code blocks that can be turned into Swagger JSON - .GitHub - fotinakis/swagger-blocks
• openapi-rails is a CRUD interface for Rails models with OpenAPI (Swagger) specification support and Swagger UI integration - GitHub - slate-studio/openapi-rails

Go

• swag automatically generates RESTful API documentation with Swagger 2.0 - GitHub - swaggo/swag 
• go-swagger (golang implementation of Swagger 2.0) is a complete suite of fully-featured, high-performance, API components to work with a Swagger API: server, client and data model - Github - Swagger 2.0 implementation for go
  
  

APISec seamlessly integrates with most of the popular API gateways and automatically pulls the API specs in OAS format for easy API registration.  For the purpose of document completion and developer curiosity, a select few are mentioned below. 

AWS API Gateway

•  get-export  is a CLI  command to export OAS from AWS API Gateway - get-export — AWS CLI 2.4.27 Command Reference 

Google Cloud Endpoints

• Generating the OpenAPI document is described here -, Adding API management | Cloud Endpoints Frameworks for App Engine 

Azure API Management

• API developers can export API definitions in OAS format - Export API definitions from API Management developer portal | Azure updates | Microsoft Azure

Apigee Edge

• Apigee Edge Proxy to OpenAPI 2.0 conversion tool. - GitHub - anil614sagar/apigee2openapi 

Postman

• Convert Postman Collections v2.1/v2.0 to OpenAPI v3.0 -  postman-to-openapi - npm 

IBM DataPower

• How to get OAS for an API from IBM DataPower Gateway (v5 compatible) and DataPower API Gateway - Get OAS from IBM DataPower

‍

Help us improve this article by sending your suggestions and comments to support@apisec.ai. Thanks!

References:

1. OpenAPI Initiative

FAQs

1. How can OpenAPI security schemes help prevent Broken Object Level Authorization (BOLA)?‍

Formalizing authentication and authorization in the specification ensures endpoints follow consistent access rules and helps automated tools validate object-level controls.

2. Is OpenAPI schema validation enough to secure your API?‍

No schema validation prevents malformed input, but doesn’t enforce business logic, authorization, or workflow integrity.

3. How does OpenAPI documentation drift impact API security?‍

Drift causes undocumented or outdated endpoints to bypass testing and governance, creating shadow API-like exposures.

4. What is schema-based input validation, and how does it reduce attack surface?‍

It restricts inputs to expected formats and values, blocking malicious payloads and reducing processing complexity.

5. How can OpenAPI specifications be used in automated security testing?‍

A well-structured REST API specification provides a blueprint for test generation, enabling tools to validate request shapes, auth models, and response behaviors consistently

‍

‍