OpenAPI

An OpenAPI Specification (OAS) is a description format for REST APIs. Swagger is a set of tools based on this specification for writing, documenting, and consuming REST APIs. For more information, see Swagger documentation.

IntelliJ IDEA provides coding assistance for OpenAPI definitions in YAML and JSON files, and integration with Swagger Codegen for generating server stubs, client libraries (SDKs), and documentation based on your OpenAPI specification.

Create an OpenAPI specification

IntelliJ IDEA recognizes a dedicated OpenAPI Specification file type with relevant coding assistance. These are regular YAML or JSON files with the definition of the OpenAPI specification version.

From the main menu, select File | New | OpenAPI Specification, or press Alt+Insert and select OpenAPI Specification.
Specify a name for the file and select the specification version and file format.

Depending on the format and version, the new OpenAPI specification file contains the following template:

openapi: 3.0.0
info:
    title: Title
    description: Title
    version: 1.0.0
servers:
    - url: 'https'
paths:

                

{
    "openapi": "3.0.0",
    "info": {
        "title": "Title",
        "description": "Title",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "https"
        }
    ],
    "paths": {

    }
}

                

swagger: "2.0"
info:
    title: Title
    description: Title
    version: 1.0.0
host: www
schemes:
    - https
paths:

                

{
    "swagger": "2.0",
    "info": {
        "title": "Title",
        "description": "Title",
        "version": "1.0.0"
    },
    "host": "www",
    "schemes": [
        "https"
    ],
    "paths": {

    }
}

                

If you start with an empty YAML or JSON file, you can type the opnp or swag live template and press Tab to insert the corresponding template text.

You can use the Endpoints tool window to see all endpoints defined in your OpenAPI specification:

URLs that you define in OpenAPI specifications in your project are available for code completion. If you are writing client code for an external specification, there is no need to add it as a file to your project for auto-completing URLs. You can add a link to the relevant remote specification.

Add a remote OpenAPI specification

In the Settings/Preferences dialog Ctrl+Alt+S, select Languages & Frameworks | OpenAPI Specification.
Click and specify the URL of the OpenAPI specification file.

Use to reload specifications that were modified.

Generate code from an OpenAPI specification

When you have a valid OpenAPI specification open, IntelliJ IDEA suggests to generate code from it:

Suggestion to generate code based on the OpenAPI specification

Click Run Codegen, configure the necessary settings, then apply the changes and run the configuration. IntelliJ IDEA generates source code files in the specified location and shows a notification with options to open the files or import them into your project as a separate module.

Swagger Codegen run configuration

IntelliJ IDEA creates a Swagger Codegen run configuration, which you can configure when you run code generation for the first time for a particular file. To modify the run configuration, open Run | Edit Configurations and select the necessary configuration, or click Edit Generation Settings at the top of the editor when the corresponding OpenAPI specification file is open.

You can configure the following common options at the top of the Swagger Codegen run configuration:

Item	Description
Name	Specify a name for the run/debug configuration to quickly identify it when editing or running the configuration, for example, from the Run popup `Shift+Alt+F10`.
Allow parallel run	Select to allow running multiple instances of this run configuration in parallel. By default, it is disabled, and when you start this configuration while another instance is still running, IntelliJ IDEA suggests to stop the running instance and start another one. This is helpful when a run/debug configuration consumes a lot of resources and there is no good reason to run multiple instances.
Store as project file	Save the file with the run configuration settings to share it with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project. By default, it is disabled, and IntelliJ IDEA stores run configuration settings in .idea/workspace.xml.

Item

Description

Name

Specify a name for the run/debug configuration to quickly identify it when editing or running the configuration, for example, from the Run popup Shift+Alt+F10.

Allow parallel run

Select to allow running multiple instances of this run configuration in parallel.

By default, it is disabled, and when you start this configuration while another instance is still running, IntelliJ IDEA suggests to stop the running instance and start another one. This is helpful when a run/debug configuration consumes a lot of resources and there is no good reason to run multiple instances.

Store as project file

Save the file with the run configuration settings to share it with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project.

By default, it is disabled, and IntelliJ IDEA stores run configuration settings in .idea/workspace.xml.

General Settings

Item	Description
Specification path	Path to the OpenAPI specification.
Generate files to	Path to the directory for the generated files.
Generator path	Path to the generator (the executable JAR file). You can either manually specify the path to a local generator or select to use the latest available version from Maven Central.
Language	The target language of the generated code.
Configure generator	Provide configuration parameters that depend on the target language. With .json file: Specify the path to config.json with configuration parameters. With properties: Specify parameters manually.

Advanced Settings

Item	Description
Custom templates path	Path to a directory with your Mustache templates.
JRE	Java runtime to use for running Swagger Codegen.
Show debug logs	Write debug messages to the log.

Before launch

Add tasks to perform before starting the run configuration in the specified order. For example, you can run another configuration or an external tool first.

Item	Description
Show this page	Show this run configuration settings dialog before starting it.
Activate tool window	Open the Run tool window when this configuration starts. If this is disabled, to open the tool window, select View \| Tool Windows \| Run `Alt+4`.

Last modified: 15 April 2020