开放API

OpenAPI 规范 (OAS) 是 REST API 的描述格式。Swagger是一组基于此规范的工具，用于编写、记录和使用 REST API。有关详细信息，请参阅Swagger 文档。

PhpStorm 为 YAML 和 JSON 文件中的 OpenAPI 定义提供编码帮助，并与Swagger Codegen集成以根据您的 OpenAPI 规范生成服务器存根、客户端库 (SDK) 和文档。此外，您可以为定义的端点创建 HTTP 请求并通过内置的HTTP Client执行它们。

创建 OpenAPI 规范

PhpStorm通过相关的编码帮助识别专用的OpenAPI 规范文件类型。这些是具有 OpenAPI 规范版本定义的常规 YAML 或 JSON 文件。

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

                    openapi：3.0.0 信息：标题：标题描述：标题版本：1.0.0 服务器：- url：'https' 路径：

                

                    {“openapi”：“3.0.0”，“信息”：{“标题”：“标题”，“描述”：“标题”，“版本”：“1.0.0”}，“服务器”：[{“ url": "https" } ], "paths": { } }

                

                    招摇：“2.0”信息：标题：标题描述：标题版本：1.0.0主机：www方案：-https路径：

                

                    {“招摇”：“2.0”，“信息”：{“标题”：“标题”，“描述”：“标题”，“版本”：“1.0.0”}，“主机”：“www”，“方案”：[“https”]，“路径”：{}}

                

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

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

在Settings/Preferences对话框 ( Ctrl+Alt+S) 中，选择Languages & Frameworks | OpenAPI 规范。
单击远程规范列表并指定 OpenAPI 规范文件的 URL，或在 SwaggerHub 上查找OpenAPI规范。

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

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

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

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

这会生成一个 Markdown 文件，其中包含修改后的规范元素的摘要。该文件在编辑器中打开，并带有一个预览面板，可以轻松浏览更改。它显示了您选择的第二个文件与第一个相比的更改。

当您打开一个有效的 OpenAPI 规范时，您可以通过单击从中生成代码：

单击，配置必要的设置，然后应用更改并运行配置。PhpStorm 在指定位置生成源代码文件，并显示一个通知，其中包含打开文件或将它们作为单独模块导入项目的选项。

PhpStorm 创建一个Swagger Codegen 运行配置，您可以在首次为特定文件运行代码生成时配置它。要修改运行配置，请打开运行 | 编辑配置并选择必要的配置，或在打开相应的 OpenAPI 规范文件时单击编辑器顶部的。

您可以在Swagger Codegen运行配置的顶部配置以下常用选项：

姓名

为运行/调试配置指定一个名称，以便在编辑或运行配置时快速识别它，例如，从运行弹出窗口Alt+Shift+F10中。

允许并行运行

选择以允许并行运行此运行配置的多个实例。

默认情况下，它是禁用的，当您在另一个实例仍在运行时启动此配置时，PhpStorm 建议停止正在运行的实例并启动另一个实例。当运行/调试配置消耗大量资源并且没有充分理由运行多个实例时，这很有帮助。

存储为项目文件

使用运行配置设置保存文件以与其他团队成员共享。默认位置是.idea/runConfigurations。但是，如果您不想共享.idea目录，您可以将配置保存到项目中的任何其他目录。

默认情况下，它被禁用，并且 PhpStorm 将运行配置设置存储在.idea/workspace.xml中。


规范路径	OpenAPI 规范的路径。
生成文件到	生成文件的目录路径。
生成器路径	生成器的路径（可执行 JAR 文件）。您可以手动指定本地生成器的路径，也可以选择使用来自 Maven Central 的最新可用版本。
语言	生成代码的目标语言。
配置生成器	提供取决于目标语言的配置参数。使用 .json 文件：使用配置参数指定config.json的路径。例如，Java 的config.json文件可以包含以下参数： { "groupId":"com.my.company", "artifactId":"MyClient", "artifactVersion":"1.2.0", "library":"feign" } 带属性：手动指定参数。有关配置参数的信息，请参阅swagger-codegen/README.md。


自定义模板路径	带有您的Mustache 模板的目录的路径。
JRE	用于运行 Swagger Codegen 的 Java 运行时。
显示调试日志	将调试消息写入日志。

按指定顺序添加要在开始运行配置之前执行的任务。例如，您可以先运行另一个配置或外部工具。


显示此页面	在启动之前显示此运行配置设置对话框。
激活工具窗口	此配置启动时打开运行工具窗口。如果禁用此功能，要打开工具窗口，请选择查看 \| 工具窗口 \| 运行 `Alt+4`。

使用OpenAPI 规范文件时，您可以创建对指定端点的 HTTP 请求并通过内置的HTTP 客户端执行它们。

PhpStorm 将创建一个新的 HTTP 请求并将其保存在generated-requests.http 临时文件中。

使用重命名重构同时重命名定义的端点及其在 HTTP 请求中的用法。

执行以下任一操作：
- 在 OpenAPI 规范文件中，将插入符号放在要重命名的端点定义处。
- 在 HTTP 请求文件中，将插入符号放在要重命名的 URL 路径段。
选择重构 | 从主菜单或上下文菜单重命名Shift+F6，或按。
在打开的重命名对话框中，指定新端点的名称。
预览并应用更改。

PhpStorm 将重命名端点及其用途。

最后修改：2022 年 1 月 17 日