OpenAPI 3.0 Editor And Generator With A Spring Boot Example

Visual API Design, Automated API Generation
How to design APIs visually with Apicurio Studio and bootstrap RESTful API clients and server stubs for Java (Spring Boot, JAX-RS), Javascript, Python, C#, C++, Ruby, Go, PHP, Kotlin, Scala and more languages using a Swagger 2.0 or OpenAPI 3.0 specification file with OpenAPI Generator

Design your API with Swagger or OpenAPI

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.
    Apicurio - 4. edit operations
  • 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).
    Swagger Editor
  • 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.
    Swaggerhub
  • Stoplight: Allows you to create and edit OpenAPI / Swagger files with no specialized knowledge required using a visual designer.
    Stoplight

Apicurio - 1. Create a New API
Visit https://studio.apicur.io/dashboard and log in to get started designing new APIs
Apicurio - 2. Editor
From the editor, manually add paths, or add a data type to generate them
Apicurio - 3. Define a New Data Type
Enter a JSON sample and choose REST Resource to create CRUD operations
Apicurio - 4. edit operations
Add or modify desired operations on each path
Apicurio - 5. preview documentation
The documentation can be previewed by clicking 'Live Documentation'
Apicurio - 6. Export OpenAPI file
The OpenAPI specification file can be exported either as JSON or YAML
Apicurio - 7. generated file
Overview the generated specification file with a text editor

Generate a REST API server or client using the OpenAPI Generator

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

1. basic usage command
2. basic usage generated-project

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 formated. 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

3. generated-project advanced

Note

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