OpenAPI
OpenAPI 规范（OAS）是 REST API 的描述格式。 Swagger 是一套基于该规范的工具，用于编写、记录和使用 REST API。 如需更多信息，请参阅 Swagger 文档。
WebStorm 提供 OpenAPI 定义在 YAML 和 JSON 文件中的编码支持，并与 Swagger Codegen 集成，以根据您的 OpenAPI 规范生成服务器存根、客户端库（SDK）和文档。
您可以使用 Endpoints 工具窗口查看 OpenAPI 规范中定义的所有端点。
此外，您可以从 OpenAPI Specification 直接 创建 HTTP 请求 到定义的端点，并通过内置的 HTTP 客户端 执行这些请求。
在开始之前
请在 设置 | 插件 页面， Marketplace 选项卡上安装 OpenAPI Specifications 插件。
要添加 Endpoints 工具窗口 ，请在 设置 | 插件 页面， Marketplace 选项卡上安装 Endpoints 插件。
创建 OpenAPI 规范
WebStorm 识别专用 OpenAPI 规范 文件类型并提供相关的 代码辅助。 这些是具有 OpenAPI 规范版本定义的常规 YAML 或 JSON 文件。
手动创建 OpenAPI 规范
在 项目 工具窗口中，按 Alt+Insert 并从上下文菜单中选择 OpenAPI 规范。
请为文件指定一个名称并选择规范版本和文件格式。
在编辑器中打开的 OpenAPI 规范中，使用 
栏图标快速添加规范部分。
您可以在 IDE 设置中的 下，通过 用于快速规范编辑的装订区域图标 复选框禁用 边栏图标。
根据格式和版本，新的 OpenAPI 规范文件包含以下模板：
如果您从一个空的 YAML 或 JSON 文件开始，您可以输入 opnp 或 swag ，然后按 Tab 来插入相应的 实时模板。
引用单独文件中的定义
使用 OpenAPI 3.0，您可以使用 $ref 关键字引用托管在任何位置的定义。 WebStorm 为您提供路径补全、验证和快速导航。 为了完成，WebStorm 可以理解当前文件和外部文件的上下文，并建议使用指向相关元素的指针。
请输入
$ref关键字。开始输入外部定义的路径。
您可以按 Ctrl+B 快速导航到您所指的文件和元素。
预览 OpenAPI 规范
您可以使用集成的 Swagger UI 或 Redoc UI 预览 OpenAPI 规范。 当在编辑器中打开 OpenAPI 规范文件时，请使用右上角的 
和 
来显示或隐藏预览。
若要在 Swagger UI 和 Redoc UI 之间切换, 请将鼠标悬停在预览区域并点击 
。
水平分割编辑器和预览
默认情况下，编辑器和预览垂直拆分（并排），这对于宽屏显示器更为便利。 您也可以水平拆分，使预览显示在编辑器的下部，这对于竖屏显示更为便利。
右键点击 Markdown 文件选项卡的标题，然后选择 从此处向下拆分。
添加远程 OpenAPI 规范
在项目中定义的 OpenAPI 规范中的端点 URL 可用于 code completion。 如果您正在为外部规范编写客户端代码，则无需将其作为文件添加到项目中以自动完成端点 URL。 您可以添加指向相关远程规范的链接。
在 设置 对话框(Ctrl+Alt+S )中，选择 。
点击
在 远程规范 列表中并指定 OpenAPI 规范文件的 URL 或在 SwaggerHub 上查找 OpenAPI 规范。
请使用 
重新加载已修改的规范。
要添加 私人 OpenAPI 规范 ，请提供您的 API 密钥。
若要从自托管的 SwaggerHub On-Premise 实例添加 OpenAPI 规范，请指定您的实例的 URL。
比较 OpenAPI 规范
当有更新的规范版本时，您可能希望将其与较旧版本进行比较，以确保它们兼容。 一种方法是查看 变更 Ctrl+D 并比较变化的行。 然而，并非所有的变更都对兼容性至关重要。 WebStorm 可以比较 OpenAPI 规范的结构，并创建更改路径、参数、响应以及任何其他可能破坏兼容性的元素的摘要。
在 项目 工具窗口中，选择两个 OpenAPI 规范文件，右键点击它们并选择 比较OpenAPI 规范。
这会生成一个包含修改后的规范元素摘要的 Markdown 文件。 文件在编辑器中打开，并带有一个预览面板，使得导航更改变得容易。 它显示了相对于第一个文件，您第二次选择的文件中的更改。
从 OpenAPI 规范生成代码
当您打开有效的 OpenAPI 规范时，WebStorm 建议从中生成代码：
在装订区域中点击 
并选择 运行 'openapi file'。 WebStorm 在指定位置生成源代码文件，并显示通知，提供打开文件或将其作为单独模块导入项目的选项。
Swagger Codegen 运行配置
WebStorm 在对特定文件第一次运行代码生成时创建一个 OpenAPI/Swagger 代码生成器 运行配置。 要修改运行配置，请打开 并选择必要的配置，或者点击 并选择 修改运行配置。
您可以在 OpenAPI/Swagger 代码生成器 运行配置的顶部配置以下常见选项：
常规参数
条目 | 描述 |
|---|---|
名称(N) | 为运行配置指定一个名称，以便在编辑或运行时能快速识别。 |
存储为项目文件(S) | 将运行配置设置保存到文件中，以便与其他团队成员共享。 默认位置是 .idea/runConfigurations 。 但是，如果您不想共享 .idea 目录，您可以将配置保存到项目中的任何其他目录。 默认情况下，它是禁用的，WebStorm 会将运行配置设置存储在 .idea/workspace.xml 。 |
代码生成设置
条目 | 描述 |
|---|---|
输出目录 | 生成文件的目录路径。 |
代码生成器 | 代码生成器类型：
|
语言 | 生成代码的目标语言。 |
修改选项
如果某些设置被隐藏，请点击 修改选项(M) 以显示它们。
条目 | 描述 |
|---|---|
规范路径 | OpenAPI 规范的路径。 |
JRE | 用于运行 Swagger Codegen 的 Java 运行时 |
自定义模板路径 | 通向您的 Mustache 模板的目录路径。 |
生成形参
根据目标语言提供配置参数。 如需更多信息，请参阅 swagger-codegen/README.md。
在 HTTP 客户端中测试您的 OpenAPI 规范
处理 OpenAPI 规范 文件时，您可以创建到指定端点的 HTTP 请求，并通过内置的 HTTP 客户端 执行这些请求。
创建一个 HTTP 请求到一个端点
在 OpenAPI 规范文件中，点击编辑器装订区域中端点定义旁边的
。
或者，打开 ，右键点击端点，然后选择 在 HTTP 客户端 中生成请求。
WebStorm 将创建一个新的 HTTP 请求，并将其保存在 generated-requests.http 临时文件中。
如果您想快速向某个端点发送请求且不想保存它，您可以使用 HTTP 客户端 选项卡（位于 端点 工具窗口中）。
根据可用的 OpenAPI 规范，WebStorm 为请求 URL 以及请求体（JSON 格式）提供补全。 这不仅适用于本地规范，也适用于远程规范（在 IDE 设置中添加它们以启用补全）。
重命名端点及其用法
使用 重命名重构 同步重命名已定义的端点及其在 HTTP 请求中的用法。
执行以下任意操作：
在 OpenAPI 规范文件中，将文本光标放在您想要重命名的端点定义处。
在 HTTP 请求文件中，将插入符号置于您要重命名的 URL 路径段上。
在主菜单或上下文菜单中选择 ，或按 Shift+F6。
在打开的 重命名 对话框中，指定新的端点名称。
预览并应用更改。
WebStorm 将重命名该端点及其用法。
