OpenAPI

创建 OpenAPI 规范

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

手动创建 OpenAPI 规范

1. 在 项目 工具窗口中，按 Alt+Insert 并从上下文菜单中选择 OpenAPI 规范。

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

   

在编辑器中打开的 OpenAPI 规范中，使用 栏图标快速添加规范部分。

您可以在 IDE 设置中的 语言和框架 ｜ OpenAPI 规范 下，通过 用于快速规范编辑的装订区域图标 复选框禁用 边栏图标。

根据格式和版本，新的 OpenAPI 规范文件包含以下模板：

如果您从一个空的 YAML 或 JSON 文件开始，您可以输入 opnp 或 swag ，然后按 Tab 来插入相应的 实时模板。

引用单独文件中的定义

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

1. 请输入 $ref 关键字。

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

您可以按 Ctrl+B 快速导航到您所指的文件和元素。

预览 OpenAPI 规范

您可以使用集成的 Swagger UI 或 Redoc UI 预览 OpenAPI 规范。 当在编辑器中打开 OpenAPI 规范文件时，请使用右上角的 和 来显示或隐藏预览。

若要在 Swagger UI 和 Redoc UI 之间切换, 请将鼠标悬停在预览区域并点击 。

添加远程 OpenAPI 规范

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

1. 在 设置 对话框(Ctrl+Alt+S )中，选择 语言和框架 ｜ OpenAPI 规范。

2. 点击 在 远程规范 列表中并指定 OpenAPI 规范文件的 URL 或在 SwaggerHub 上查找 OpenAPI 规范。

请使用 重新加载已修改的规范。

要添加 私人 OpenAPI 规范 ，请提供您的 API 密钥。

若要从自托管的 SwaggerHub On-Premise 实例添加 OpenAPI 规范，请指定您的实例的 URL。

比较 OpenAPI 规范

当有更新的规范版本时，您可能希望将其与较旧版本进行比较，以确保它们兼容。 一种方法是查看 变更 Ctrl+D 并比较变化的行。 然而，并非所有的变更都对兼容性至关重要。 CLion 可以比较 OpenAPI 规范的结构，并创建更改路径、参数、响应以及任何其他可能破坏兼容性的元素的摘要。

从 OpenAPI 规范生成代码

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

点击 并选择 运行 'openapi file'。 CLion 在指定位置生成源代码文件，并显示通知，提供打开文件或将其作为单独模块导入项目的选项。