# OpenAPI

> **TL;DR**
> Required plugin: OpenAPI Specifications (bundled)

An OpenAPI Specification (OAS) is a description format for REST APIs. [Swagger](https://swagger.io/) is a set of tools based on this specification for writing, documenting, and consuming REST APIs. For more information, refer to [Swagger documentation](https://swagger.io/docs/specification/about/).

IntelliJ IDEA provides coding assistance for OpenAPI definitions in YAML and JSON files, and integration with [Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/) for generating server stubs, client libraries (SDKs), and documentation based on your OpenAPI specification.

> **Note:**
> IntelliJ IDEA supports OpenAPI Specification versions 2.0, 3.0, and 3.1. Version 3.2 is not supported.

You can use the [Endpoints](endpoints-tool-window.html) tool window to see all endpoints defined in your OpenAPI specifications.

![Endpoints from an OpenAPI specification](https://resources.jetbrains.com/help/img/idea/2026.2/openapi-endpoints.png)

Additionally, you can [create HTTP requests](#http-client) to defined endpoints right from an OpenAPI Specification and execute them via the built-in [HTTP Client](http-client-in-product-code-editor.html).

## Create an OpenAPI specification

IntelliJ IDEA recognizes a dedicated OpenAPI Specification file type with relevant [coding
assistance](discover-intellij-idea.html#coding-assistance). These are regular YAML or JSON files with the definition of the OpenAPI specification version.

Procedure: Create an OpenAPI Specification manually

1. In the Project tool window, press `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Ctrl+N` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `Alt+Insert` (NetBeans), `Ctrl+N` (Visual Studio), `⌘ N` (Visual Studio (macOS)), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS)) and select OpenAPI Specification from the context menu.

2. Specify a name for the file and select the specification version and file format.

![New OpenAPI specification](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_create_new_specification.png)

In an OpenAPI specification opened in the editor, use the ![Add icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.add.svg) gutter icons to quickly add specification sections.

![OpenAPI gutter icons](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_gutter_icons_add.animated.gif)

You can disable the ![Add icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.add.svg) gutter icon in the IDE settings, under `Languages & Frameworks | OpenAPI Specifications` using the Gutter icons for quick specification edits checkbox.

Depending on the selected format and version, one of the preconfigured [file templates](using-file-and-code-templates.html) is used for a new OpenAPI specification file.

If you start with an empty YAML or JSON file, you can type `opnp` or `swag` and press `Tab` (Windows), `⇥` (macOS), `⇥` (IntelliJ IDEA Classic (macOS)), `⇥` (macOS System Shortcuts), `Tab` (XWin), `Tab` (GNOME), `Tab` (KDE), `Tab` (Emacs), `Tab` (Sublime Text), `⇥` (Sublime Text (macOS)), `Tab` (NetBeans), `Tab` (Visual Studio), `⇥` (Visual Studio (macOS)), `Tab` (Eclipse), `⇥` (Eclipse (macOS)) to insert the corresponding [live template](using-live-templates.html).

Procedure: Generate an OpenAPI Specification based on URL mapping

If you have a REST controller with URL mapping in your source code, you can quickly generate an OpenAPI Specification from the controller code.

1. Click ![Show available actions for URL](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.inlayGlobe.svg) next to a controller path.

2. Select Generate OpenAPI draft.

![Generate OpenAPI action](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_generate_action.png)

The generated file is saved under `Scratches and Consoles | OpenAPI Specifications`.

The action is also available in the Endpoints tool window where you can also generate an OpenAPI specification for the entire module.

Procedure: Reference a definition from a separate file

With OpenAPI 3.0, you can reference a definition hosted on any location using the [$ref](https://swagger.io/docs/specification/using-ref/) keyword. IntelliJ IDEA provides you with path completion, validation, and quick navigation. For completion, IntelliJ IDEA understands the context of the current file and of external files, and suggests using pointers to relevant elements.

1. Enter the `$ref` keyword.

2. Start typing the path to the external definition.

You can press `Ctrl+B` (Windows), `⌘ B` (macOS), `⌘ B` (IntelliJ IDEA Classic (macOS)), `⌘ B` (macOS System Shortcuts), `Ctrl+B` (XWin), `Ctrl+B` (GNOME), `Ctrl+B` (KDE), `Ctrl+Alt+G` (Emacs), `F12` (Sublime Text), `F12` (Sublime Text (macOS)), `Ctrl+B` (NetBeans), `F12` (Visual Studio), `F12` (Visual Studio (macOS)), `F3` (Eclipse), `F3` (Eclipse (macOS)) to quickly navigate to the file and element you refer to.

![OpenAPI use ref](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_ref.animated.gif)

## Preview an OpenAPI specification

You can preview an OpenAPI specification using the integrated Swagger UI or Redoc UI. When an OpenAPI specification file is opened in the editor, use ![the Open Editor Preview button](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.previewOnly.svg) and ![the Editor only button](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.editorOnly.svg) in the top-right corner to show or hide the preview.

To switch between Swagger UI and Redoc UI, hover over the preview area and click ![Switch View](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.actions.properties.svg).

Swagger:

![Swagger Preview](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_preview_swaggerui.png)

Redoc:

![Swagger Preview](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_preview_redocui.png)

Procedure: Split editor and preview horizontally

By default, the editor and the preview are split vertically (side by side), which is convenient for wide monitors. You can also split it horizontally, so that the preview is displayed in the lower part of the editor, which is more convenient for portrait displays.

1. In the top-right corner of the editor, click ![the Open Editor Preview button](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.editorPreview.svg) to open the Editor Preview pane.

2. Click ![the Open Editor Preview button](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.editorPreviewVertical.svg) to split the editor and the preview horizontally.

## Add a remote OpenAPI specification

Endpoint URLs that you define in OpenAPI specifications in your project are available for [code completion](auto-completing-code.html). 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 endpoint URLs. You can add a link to the relevant remote specification.

Procedure:

1. In the Settings dialog (`Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))), select `Languages & Frameworks | OpenAPI Specifications`.

2. Click ![the Add button](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) in the Remote Specifications  list and specify the URL of an OpenAPI specification file or find an OpenAPI specification on [SwaggerHub](https://app.swaggerhub.com/).

![The OpenAPI Specification settings](https://resources.jetbrains.com/help/img/idea/2026.2/openapi-remote-spec.png)

Use ![The Reload All Specifications button](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.refresh.svg) to reload specifications that were modified.

To add [private OpenAPI
specifications](https://app.swaggerhub.com/help/apis/public-and-private-apis), provide your API key.

To add OpenAPI specifications from a self-hosted [SwaggerHub On-Premise](https://app.swaggerhub.com/help/enterprise/index) instance, specify the URL of your instance.

## Compare OpenAPI specifications

When there is a newer specification version, you probably want to compare it against the older version to make sure that they are compatible. One way is to look at the [diff](comparing-files-and-folders.html#comparing_files) `Ctrl+D` (Windows), `⌘ D` (macOS), `⌘ D` (IntelliJ IDEA Classic (macOS)), `⌘ D` (macOS System Shortcuts), `Ctrl+D` (XWin), `Ctrl+D` (GNOME), `Ctrl+D` (KDE), `Ctrl+D` (Emacs), `Ctrl+D` (Sublime Text), `⌘ D` (Sublime Text (macOS)), `Ctrl+D` (NetBeans), `Ctrl+D` (Visual Studio), `⌘ D` (Visual Studio (macOS)), `Ctrl+D` (Eclipse), `⌘ D` (Eclipse (macOS)) and compare lines that changed. However, not all changes are critical for compatibility. IntelliJ IDEA can compare the structure of OpenAPI specifications and create a summary of changed paths, parameters, responses, and any other elements that may break the compatibility.

Procedure:

* In the Project tool window, select two OpenAPI specification files, right-click them and select Compare OpenAPI Specifications.

This generates a Markdown file with a summary of modified specification elements. The file opens in the editor with a preview panel that makes it easy to navigate the changes. It shows the changes in the file that you selected second compared to the first one.

## Generate code from an OpenAPI specification

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

![Generate code based on the OpenAPI specification](https://resources.jetbrains.com/help/img/idea/2026.2/openapi-codegen.png)

Click ![the Run button](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.gutter.run.svg) in the gutter and select Run 'openapi file'. 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.

> **Note:**
> IntelliJ IDEA can generate code from an OpenAPI specification for the most popular languages, which include Java, Kotlin, JavaScript, TypeScript, Python, PHP, Go, C#, C++, C, and so on. For a full list of supported languages, refer to the [OpenAPI Generator documentation](https://openapi-generator.tech/docs/generators/).

### Swagger Codegen run configuration

IntelliJ IDEA creates a OpenAPI/Swagger Code Generator  [run configuration](run-debug-configuration.html) 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 ![the Run button](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.gutter.run.svg) in the gutter and select Modify Run Configuration.

You can configure the following common options at the top of the OpenAPI/Swagger Code Generator  run configuration:

#### General parameteres

| Item | Description |
| --- | --- |
| Name | Specify a name for the run configuration to quickly identify it among others when editing or running. |
| 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`.    |

#### Code Generation Settings

| Item | Description |
| --- | --- |
|   Output Directory   | Path to the directory for the generated files. |
|  Code Generator  |     Type of code generator:        * OpenAPI Generator 7    * OpenAPI Generator 6    * OpenAPI Generator 5    * OpenAPI Generator 4    * Swagger Codegen 3    * Swagger Codegen 2                             |
|   Language   | The target language of the generated code. |

#### Modify options

If some of the settings are hidden, click  Modify options  to show them.

| Item | Description |
| --- | --- |
| Specification Path | Path to the OpenAPI specification. |
| JRE | Java runtime to use for running Swagger Codegen |
| Custom Templates Path  | Path to a directory with your [Mustache templates](https://mustache.github.io/). |

#### Generation Parameters

Provide configuration parameters depending on the target language. For more information, refer to the [swagger-codegen/README.md](https://github.com/swagger-api/swagger-codegen#customizing-the-generator).

## Test your OpenAPI specification in the HTTP client

When working with OpenAPI Specification files, you can create HTTP requests to the specified endpoints and execute them via the built-in [HTTP client](http-client-in-product-code-editor.html).

Procedure: Create an HTTP request to an endpoint

* In an OpenAPI specification file, click ![the Open in HTTP Client button](https://resources.jetbrains.com/help/img/idea/2026.2/swagger.icons.endpointGutter.svg) in the editor gutter next to the endpoint definition.

* Alternatively, open `View | Tool Windows | Endpoints` , right-click an endpoint, and select Generate Request in HTTP Client.

IntelliJ IDEA will create a new HTTP request and save it in the `generated-requests.http` [scratch file](http-client-in-product-code-editor.html#creating-http-request-files).

If you want to quickly send a request to an endpoint and do not want to save it, you can use the HTTP Client tab in the Endpoints tool window.

IntelliJ IDEA provides completion for the request URL and for the request body (in JSON format) based on the available OpenAPI specifications. This applies not only to local, but also to remote specifications ([add them in the IDE settings](#remote-spec) to enable completion).

![Body completion](https://resources.jetbrains.com/help/img/idea/2026.2/openapi_body_completion.animated.gif)

Procedure: Rename an endpoint and its usages

Use the [Rename refactoring](rename-refactorings.html) to rename the defined endpoint and its usages in HTTP requests simultaneously.

1. Do any of the following:

* In an OpenAPI specification file, place the caret at the endpoint's definition you want to rename.

* In an HTTP request file, place the caret at the URL path segment you want to rename.

2. Select `Refactor | Rename` from the main menu or the context menu, or press `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R` (NetBeans), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS)).

3. In the Rename dialog that opens, specify the new endpoint's name.

4. Preview and apply changes.

IntelliJ IDEA will rename the endpoint and its usages.