OpenAPI
OpenAPI 规范（OAS）是用于描述 REST API 的格式。 Swagger 是基于此规范的一组工具，用于编写、记录和使用 REST API。 如需了解详情，请参阅 Swagger documentation。
WebStorm 为 YAML 和 JSON 文件中的 OpenAPI 定义提供代码辅助，并集成 Swagger Codegen ，以基于您的 OpenAPI 规范生成服务器桩代码、客户端库（SDK）和文档。
您可以使用 Endpoints 工具窗口查看 OpenAPI 规范中定义的所有端点。
此外，您还可以直接从 OpenAPI 规范中 创建 HTTP 请求 ，并通过内置的 HTTP Client 执行它们。
开始之前
在 设置｜插件 页面、 Marketplace 选项卡中安装 OpenAPI Specifications 插件。
要添加 Endpoints 工具窗口 ，请安装 Endpoints 插件（设置｜插件 页面， Marketplace 选项卡）。
创建 OpenAPI 规范
WebStorm 识别专用的 OpenAPI 规范 文件类型，并提供相关的 代码辅助。 这些是普通的 YAML 或 JSON 文件，包含 OpenAPI 规范版本的定义。
手动创建 OpenAPI 规范
在 项目 工具窗口中，按下 Alt+Insert 并从上下文菜单中选择 OpenAPI 规范。
为文件指定名称，并选择规范版本及文件格式。
在编辑器中打开的 OpenAPI 规范中，使用 
行号图标可快速添加规范部分。
您可以在 IDE 设置中，通过 下的 用于快速规范编辑的装订区域图标 复选框禁用 行号图标。
根据格式和版本，新建的 OpenAPI 规范文件包含以下模板：
如果从空的 YAML 或 JSON 文件开始，您可以键入 opnp 或 swag ，然后按 Tab 插入对应的 live template。
从单独文件引用定义
使用 OpenAPI 3.0，您可以使用 $ref 关键字引用托管在任意位置的定义。 WebStorm 提供路径补全、校验和快速导航功能。 在补全时，WebStorm 能理解当前文件及外部文件的上下文，并建议使用指针引用相关元素。
输入关键字
$ref。开始键入外部定义的路径。
您可以按 Ctrl+B 快速导航到引用的文件及元素。
预览 OpenAPI 规范
您可以使用集成的 Swagger UI 或 Redoc UI 预览 OpenAPI 规范。 打开 OpenAPI 规范文件后，使用右上角的 
和 
按钮显示或隐藏预览。
要在 Swagger UI 和 Redoc UI 之间切换，请将鼠标悬停在预览区域，并点击 
。
水平拆分编辑器和预览
默认情况下，编辑器和预览是垂直（并排）拆分的，适用于宽屏显示器。 您也可以将其水平拆分，使预览显示在编辑器的下方，更适合竖屏显示器。
右键点击 Markdown 文件选项卡的标题并选择 从此拆分
添加远程 OpenAPI 规范
在项目中的 OpenAPI 规范中定义的端点 URL 可用于 代码补全。 如果您正在为外部规范编写客户端代码，则无需将其作为文件添加到项目中以实现端点 URL 的自动补全。 您可以添加指向相关远程规范的链接。
在 设置 对话框中（Ctrl+Alt+S ），选择 。
在 远程规范 列表中点击
，然后指定一个 OpenAPI 规范文件的 URL，或在 SwaggerHub 上查找 OpenAPI 规范。
使用 
重新加载已修改的规范。
要添加 私有 OpenAPI 规范 ，请提供您的 API 密钥。
要从自托管的 SwaggerHub On-Premise 实例添加 OpenAPI 规范，请指定您的实例 URL。
比较 OpenAPI 规范
当存在较新的规范版本时，您可能希望将其与旧版本进行对比，以确保它们兼容。 一种方式是查看 diff 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 client 执行这些请求。
创建指向端点的 HTTP 请求
在 OpenAPI 规范文件中，点击编辑器边距中端点定义旁的
。
或者，打开 ，右键单击某个端点，并选择 在 HTTP Client 中生成请求。
WebStorm 会创建一个新的 HTTP 请求，并将其保存到 generated-requests.http 临时文件 中。
如果您希望快速向某个端点发送请求且不希望保存请求，可以使用 HTTP Client 工具窗口中的 端点 选项卡。
WebStorm 会根据已有的 OpenAPI 规范为请求 URL 和请求正文（JSON 格式）提供补全功能。 该功能不仅适用于本地规范，还适用于远程规范（在 IDE 设置中添加 即可启用补全）。
重命名端点及其用法
使用 重命名重构 可同时重命名已定义端点以及 HTTP 请求中的引用。
请执行以下任一操作：
在 OpenAPI 规范文件中，将光标放在您要重命名的端点定义处。
在 HTTP 请求文件中，将光标放在要重命名的 URL 路径段上。
从主菜单或上下文菜单中选择 ，或按下 Shift+F6。
在打开的 重命名 对话框中，指定新的端点名称。
预览并应用更改。
WebStorm 将会重命名端点及其所有引用。
