Tutorials

Generating OpenAPI Specification (OAS) documentation for your REST APIs

April 10, 2022
4 min read

TLDR Key Takeaways

🔸

🔸

🔸

🔸

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

Spring

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

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

Ruby

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

Google Cloud Endpoints

Azure API Management

Apigee Edge

Postman

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

References:

  1. OpenAPI Initiative
"x" icon
Download Your Copy Today!
Get The Ultimate API Security Checklist [eBook]
Similar Posts
Learn how to take your API security to the next level.

Check out our latest eBook