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