OpenAPI 3.0 Editor And Generator With A Spring Boot Example

OpenAPI Specification and Swagger Specification are REST API description formats that can be written in YAML or JSON and are readable to both humans and machines. They allow you to describe your API endpoints, supported operations and parameters, expected inputs and outputs, authentication methods and specify many more information.

OpenAPI is an upgraded version of Swagger that adds major improvements and new functionality including: increased reusability, extended JSON Schema functionality, and enhanced security definitions. It starts with the version 3.0 (Swagger being the version 2.0 of OpenAPI).

Many tools can be used to design and generate the Swagger or OpenAPI specification file:

• Apicurio Studio: You can design with Apicurio your API without prior knowledge of the OpenAPI specification using a visual editor. You can also generate a model and REST endpoints by simply providing a JSON sample: data types will automatically by deduced.

• Swagger Editor: OpenAPI text editor with auto-completion and live documentation preview that can be used if you are more familiar with the OpenAPI or Swagger specifications. You can also use the Insert menu to add paths, operations etc. (not available when using the Swagger 2 format).

• SwaggerHub: A centralized API development platform integrated to the Swagger framework with advanced capabilities to build, document, manage, and deploy APIs. It provides along the text-based editor a visual editor (with reduced editing capabilities) and a live preview of the generated swagger docs.

• Stoplight: Allows you to create and edit OpenAPI / Swagger files with no specialized knowledge required using a visual designer.

OpenAPI Generator is a tool that can generate API clients and server stubs using as an input an OpenAPI or Swagger specification file. It's a fork of the swagger-codegen generator that can be launched using a CLI with npm, docker and Homebrew.

The full list of supported Languages/Frameworks is available in the following link: https://openapi-generator.tech/docs/generators

Maven and Gradle plugins are also available to automate the code generation in your existing projects.

Installation

1. Node.js and npm are required to generate your API from the command line using npm. You can download them from the following link: https://nodejs.org/en/download/
2. Install the latest version of the tool globally so that it can be exposed on the command line using npm:

   npm install @openapitools/openapi-generator-cli -g

Basic usage

To generate your REST API server or client from an OpenAPI file, run the following command:

openapi-generator generate -i <openapi-file> -g <generator-id> -o <output-path>

with the parameters being:

• <openapi-file>: the OpenAPI file path
• <generator-id>: the name of the language / framework (as listed here, can also be listed using openapi-generator list)
• <output-path>: the path where the project will be generated

Example:

openapi-generator generate -i my-api.yaml -g spring -o C:\tmp\my-api

Advanced usage

You can customize the generated project package name and other aspects using command line flags that can be listed with the command openapi-generator help generate.

With the -c <configuration file> flag, you can specify the path of a file containing configuration properties specific to the chosen language / framework. This file can be either json or yaml formatted. The supported properties for each language can be listed with openapi-generator config-help -g <generator-id> or can be viewed by selecting the appropriate entry in https://openapi-generator.tech/docs/generators.

Example:

config.json:

{
  "basePackage": "com.myorg.myapp",
  "configPackage": "com.myorg.myapp.config",
  "apiPackage": "com.myorg.myapp.controllers",
  "modelPackage": "com.myorg.myapp.domain",
  "groupId": "com.myorg",
  "artifactId": "my-app",
  "artifactVersion": "0.1.0"
}

openapi-generator generate -i my-api.yaml -g spring -c config.json -o C:\tmp\my-api

Note

The configuration properties can also be specified from the command line using the flag: --additional-properties=key1=value1,key2=value2