# OpenAPI

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

> **TL;DR**
> 必需插件： [OpenAPI Specifications](https://plugins.jetbrains.com/plugin/14394-openapi-specifications/)

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

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

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

## 创建 OpenAPI 规范

CLion 识别专用   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)), `⌘ N` (Xcode), `Ctrl+N` (Visual Studio), `⌘ N` (Visual Studio (macOS)), `Alt+Insert` (ReSharper), `⌥ Insert` (ReSharper (macOS)), `Alt+Insert` (QtCreator), `Alt+Insert` (QtCreator (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS))并从上下文菜单中选择   OpenAPI 规范  。

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

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

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

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

您可以在 IDE 设置中的  `语言 & 框架 | OpenAPI 规范`  下，通过   用于快速规范编辑的装订区域图标   复选框禁用 ![添加图标](https://resources.jetbrains.com/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)), `⇥` (Xcode), `Tab` (Visual Studio), `⇥` (Visual Studio (macOS)), `Tab` (ReSharper), `⇥` (ReSharper (macOS)), `Tab` (QtCreator), `⇥` (QtCreator (macOS)), `Tab` (NetBeans), `Tab` (Eclipse), `⇥` (Eclipse (macOS)) 来插入相应的 [实时模板](using-live-templates.html)。

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

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

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

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

## 预览 OpenAPI 规范

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

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

Swagger:

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

Redoc:

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

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

默认情况下，编辑器和预览是垂直分割的（并排），这对宽屏显示器来说很方便。 您也可以水平分割，这样预览将显示在编辑器的下部，这对纵向显示器来说更方便。

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

2. 点击 ![“打开编辑器预览”按钮](https://resources.jetbrains.com/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)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)))中，选择  `语言 & 框架 | OpenAPI 规范` 。

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

![OpenAPI 规范设置](https://resources.jetbrains.com/help/img/idea/2026.3/ac_openapi_remote_spec.png)

请使用 ![重新加载所有规格按钮](https://resources.jetbrains.com/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)), `⌘ D` (Xcode), `Ctrl+D` (Visual Studio), `⌘ D` (Visual Studio (macOS)), `Ctrl+D` (ReSharper), `⌘ D` (ReSharper (macOS)), `Ctrl+D` (QtCreator), `⌘ D` (QtCreator (macOS)), `Ctrl+D` (NetBeans), `Ctrl+D` (Eclipse), `⌘ D` (Eclipse (macOS))并比较变化的行。 然而，并非所有的变更都对兼容性至关重要。 CLion 可以比较 OpenAPI 规范的结构，并创建更改路径、参数、响应以及任何其他可能破坏兼容性的元素的摘要。

Procedure:

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

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

## 从 OpenAPI 规范生成代码

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

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

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

### Swagger Codegen 运行配置

CLion 在对特定文件第一次运行代码生成时创建一个   OpenAPI/Swagger 代码生成器​   [运行配置](run-debug-configuration.html)。 要修改运行配置，请打开  `运行 | 编辑配置`  并选择必要的配置，或者点击 ![“运行”按钮](https://resources.jetbrains.com/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)。

