# OpenAPI规范

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

> **TL;DR**
> 必需插件：  OpenAPI 规范 （捆绑）

OpenAPI 规范 (OAS) 是 REST API 的描述格式。 [Swagger](https://swagger.io/) 是一套基于该规范的工具，用于编写、记录和使用 REST API。 如需更多信息，请参阅 [Swagger 文档](https://swagger.io/docs/specification/about/)。

IntelliJ IDEA 提供 OpenAPI 定义在 YAML 和 JSON 文件中的编码支持，并与 [Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/) 集成，以根据您的 OpenAPI 规范生成服务器存根、客户端库（SDK）和文档。

> **Note:**
> IntelliJ IDEA 支持 OpenAPI 规范 2.0、3.0 和 3.1 版本。 不支持版本 3.2。

您可以使用 [Endpoints](endpoints-tool-window.html) 工具窗口查看 OpenAPI 规范中定义的所有端点。

![来自 OpenAPI 规范的端点](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi-endpoints.png)

此外，您可以从 OpenAPI Specification 直接 [创建 HTTP 请求](#http-client) 到定义的端点，并通过内置的 [HTTP 客户端](http-client-in-product-code-editor.html) 执行这些请求。

## 创建 OpenAPI 规范

IntelliJ IDEA 识别专用   OpenAPI 规范   文件类型并提供相关的 [代码辅助](null)。 这些是具有 OpenAPI 规范版本定义的常规 YAML 或 JSON 文件。

Procedure: 手动创建 OpenAPI 规范

1. 在   项目  工具窗口中，按 `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)), `Ctrl+N` (Visual Studio), `⌘ N` (Visual Studio (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS))并从上下文菜单中选择   OpenAPI 规范  。

2. 请为文件指定一个名称并选择规范版本和文件格式。

![新的 OpenAPI 规范](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi_create_new_specification.png)

在编辑器中打开的 OpenAPI 规范中，使用 ![添加图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg) 栏图标快速添加规范部分。

![OpenAPI 装订区域图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi_gutter_icons_add.animated.gif)

您可以在 IDE 设置中的  `语言＆框架 | OpenAPI 规范`  下，通过   用于快速规范编辑的装订区域图标   复选框禁用 ![添加图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg) 边栏图标。

根据所选的格式和版本，将使用预配置的 [文件模板](using-file-and-code-templates.html)之一来创建新的 OpenAPI 规范文件。

如果您从一个空的 YAML 或 JSON 文件开始，您可以输入  `opnp`  或  `swag` ，然后按 `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` (Visual Studio), `⇥` (Visual Studio (macOS)), `Tab` (NetBeans), `Tab` (Eclipse), `⇥` (Eclipse (macOS)) 来插入相应的 [实时模板](using-live-templates.html)。

Procedure: 根据 URL 映射生成 OpenAPI 规范

如果您的源代码中有 URL 映射的 REST controller，您可以快速从 controller 代码生成 OpenAPI 规范。

1. 点击 ![显示可用于 URL 的操作](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.actions.inlayGlobe.svg) 旁边的控制器路径。

2. 选择   生成 OpenAPI 草稿  。

![生成 OpenAPI 操作](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi_generate_action.png)

生成的文件保存在  `涂鸦和控制台 | OpenAPI 规范` 下。

此操作也可以在   端点  工具窗口中使用，您还可以为整个模块生成 OpenAPI 规范。

Procedure: 引用单独文件中的定义

使用 OpenAPI 3.0，您可以使用 [$ref](https://swagger.io/docs/specification/using-ref/) 关键字引用托管在任何位置的定义。 IntelliJ IDEA 为您提供路径补全、验证和快速导航。 为了完成，IntelliJ IDEA 可以理解当前文件和外部文件的上下文，并建议使用指向相关元素的指针。

1. 请输入  `$ref` 关键字。

2. 开始输入外部定义的路径。

您可以按 `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)), `F12` (Visual Studio), `F12` (Visual Studio (macOS)), `Ctrl+B` (NetBeans), `F3` (Eclipse), `F3` (Eclipse (macOS)) 快速导航到您所指的文件和元素。

![OpenAPI 使用 ref](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi_ref.animated.gif)

## 预览 OpenAPI 规范

您可以使用集成的 Swagger UI 或 Redoc UI 预览 OpenAPI 规范。 当在编辑器中打开 OpenAPI 规范文件时，请使用右上角的 ![打开编辑器预览按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.previewOnly.svg) 和 ![仅限 Editor 按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.editorOnly.svg) 来显示或隐藏预览。

若要在 Swagger UI 和 Redoc UI 之间切换, 请将鼠标悬停在预览区域并点击 ![切换视图](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.actions.properties.svg)。

Swagger:

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

Redoc:

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

Procedure: 水平拆分编辑器和预览

默认情况下，编辑器和预览会垂直拆分（并排显示），这对于宽屏显示器很方便。 也可以水平拆分，使预览显示在编辑器下方，这对于纵向显示器更方便。

1. 在编辑器右上角，点击 ![打开编辑器预览按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.editorPreview.svg) 打开   编辑器预览   窗格。

2. 点击 ![打开编辑器预览按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.editorPreviewVertical.svg) 以水平拆分编辑器和预览。

## 添加远程 OpenAPI 规范

在项目中定义的 OpenAPI 规范中的端点 URL 可用于 [code completion](auto-completing-code.html)。 如果您正在为外部规范编写客户端代码，则无需将其作为文件添加到项目中以自动完成端点 URL。 您可以添加指向相关远程规范的链接。

Procedure:

1. 在   设置  对话框（ `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` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))）中，选择  `语言＆框架 | OpenAPI 规范` 。

2. 点击 !["添加"按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg) 在   远程规范   列表中并指定 OpenAPI 规范文件的 URL 或在 [SwaggerHub](https://app.swaggerhub.com/) 上查找 OpenAPI 规范。

![OpenAPI 规范设置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi-remote-spec.png)

请使用 ![重新加载所有规格按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.actions.refresh.svg) 重新加载已修改的规范。

要添加 [私人 OpenAPI 规范](https://app.swaggerhub.com/help/apis/public-and-private-apis)，请提供您的 API 密钥。

若要从自托管的 [SwaggerHub On-Premise](https://app.swaggerhub.com/help/enterprise/index) 实例添加 OpenAPI 规范，请指定您的实例的 URL。

## 比较 OpenAPI 规范

当有更新的规范版本时，您可能希望将其与较旧版本进行比较，以确保它们兼容。 一种方法是查看 [变更](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` (Visual Studio), `⌘ D` (Visual Studio (macOS)), `Ctrl+D` (NetBeans), `Ctrl+D` (Eclipse), `⌘ D` (Eclipse (macOS))并比较变化的行。 然而，并非所有的变更都对兼容性至关重要。 IntelliJ IDEA 可以比较 OpenAPI 规范的结构，并创建更改路径、参数、响应以及任何其他可能破坏兼容性的元素的摘要。

Procedure:

* 在   项目  工具窗口中，选择两个 OpenAPI 规范文件，右键点击它们并选择   比较 OpenAPI 规范  。

这会生成一个包含修改后的规范元素摘要的 Markdown 文件。 文件在编辑器中打开，并带有一个预览面板，使得导航更改变得容易。 它显示了相对于第一个文件，您第二次选择的文件中的更改。

## 从 OpenAPI 规范生成代码

当您打开有效的 OpenAPI 规范时，IntelliJ IDEA 建议从中生成代码：

![根据 OpenAPI 规范生成代码](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi-codegen.png)

在装订区域中点击 ![运行按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.gutter.run.svg) 并选择   运行 'openapi file'  。 IntelliJ IDEA 在指定位置生成源代码文件，并显示通知，提供打开文件或将其作为单独模块导入项目的选项。

> **Note:**
> IntelliJ IDEA 可以根据 OpenAPI 规范生成最最受欢迎的语言的代码，这些语言包括 Java、Kotlin、JavaScript、TypeScript、Python、PHP、Go、C#、C++、C 等。 有关受支持语言的完整列表，请参阅 [OpenAPI Generator 文档](https://openapi-generator.tech/docs/generators/)。

### Swagger Codegen 运行配置

IntelliJ IDEA 在对特定文件第一次运行代码生成时创建一个   OpenAPI/Swagger 代码生成器   [运行配置](run-debug-configuration.html)。 要修改运行配置，请打开  `运行 | 编辑配置`  并选择必要的配置，或者点击 ![运行按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/workspace.xml` 。     |

#### 代码生成设置

|  条目  |  描述  |
| --- | --- |
|    输出目录    |  生成文件的目录路径。  |
|    代码生成器    |     代码生成器类型：        * OpenAPI Generator 7    * OpenAPI Generator 6    * OpenAPI Generator 5    * OpenAPI Generator 4    * Swagger Codegen 3    * Swagger Codegen 2    |
|    语言    |  生成代码的目标语言。  |

#### 修改选项

如果某些设置被隐藏，请点击   修改选项  以显示它们。

|  条目  |  描述  |
| --- | --- |
|    规范路径    |  OpenAPI 规范的路径。  |
|    JRE    |  用于运行 Swagger Codegen 的 Java 运行时  |
|    自定义模板路径    |  通向您的 [Mustache 模板](https://mustache.github.io/)的目录路径。  |

#### 生成参数

根据目标语言提供配置参数。 如需更多信息，请参阅 [swagger-codegen/README.md](https://github.com/swagger-api/swagger-codegen#customizing-the-generator)。

## 在 HTTP 客户端中测试您的 OpenAPI 规范

处理   OpenAPI 规范   文件时，您可以创建到指定端点的 HTTP 请求，并通过内置的 [HTTP 客户端](http-client-in-product-code-editor.html) 执行这些请求。

Procedure: 创建一个 HTTP 请求到一个端点

* 在 OpenAPI 规范文件中，点击编辑器装订区域中端点定义旁边的 ![在 HTTP 客户端中打开按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/swagger.icons.endpointGutter.svg)。

* 或者，打开  `视图 | 工具窗口 | 端点` ，右键点击端点，然后选择   在 HTTP 客户端 中生成请求  。

IntelliJ IDEA 将创建一个新的 HTTP 请求，并将其保存在  `generated-requests.http`  [临时文件](http-client-in-product-code-editor.html#creating-http-request-files) 中。

如果您想快速向某个端点发送请求且不想保存它，您可以使用   HTTP 客户端   选项卡（位于   端点   工具窗口中）。

根据可用的 OpenAPI 规范，IntelliJ IDEA 为请求 URL 以及请求体（JSON 格式）提供补全。 这不仅适用于本地规范，也适用于远程规范（ [在 IDE 设置中添加它们](#remote-spec)以启用补全）。

![请求体补全](https://resources.jetbrains.com.cn/help/img/idea/2026.3/openapi_body_completion.animated.gif)

Procedure: 重命名端点及其用法

使用 [重命名重构](rename-refactorings.html) 同步重命名已定义的端点及其在 HTTP 请求中的用法。

1. 执行以下任一操作：

* 在 OpenAPI 规范文件中，将文本光标放在您想要重命名的端点定义处。

* 在 HTTP 请求文件中，将插入符号置于您要重命名的 URL 路径段上。

2. 在主菜单或上下文菜单中选择  `重构 | 重命名` ，或按 `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, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Ctrl+R` (NetBeans), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS))。

3. 在打开的   重命名   对话框中，指定新的端点名称。

4. 预览并应用更改。

IntelliJ IDEA 将重命名该端点及其用法。