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