IntelliJ IDEA
 
2023.2
快捷方式：Windows
获取 IntelliJ IDEA
  1. 非 JVM 技术
  2. OpenAPI

最终的
OpenAPI

最后修改时间：2023 年 9 月 7 日

所需插件：OpenAPI 规范（捆绑）

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

IntelliJ IDEA 为 YAML 和 JSON 文件中的 OpenAPI 定义提供编码帮助，并与Swagger Codegen集成以根据 OpenAPI 规范生成服务器存根、客户端库 (SDK) 和文档。

您可以使用端点工具窗口查看 OpenAPI 规范中定义的所有端点。

OpenAPI 规范中的端点

此外，您可以直接根据 OpenAPI 规范创建对已定义端点的 HTTP 请求，并通过内置HTTP 客户端执行它们。

创建 OpenAPI 规范

IntelliJ IDEA 可识别专用的OpenAPI 规范文件类型以及相关编码帮助。这些是常规 YAML 或 JSON 文件，包含 OpenAPI 规范版本的定义。

手动创建 OpenAPI 规范

  1. 转到文件| 新 | OpenAPI 规范，或按并选择OpenAPI 规范。AltInsert

  2. 指定文件名称并选择规范版本和文件格式。

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

openapi: 3.0.0
info:
    title: Title
    description: Title
    version: 1.0.0
servers:
    - url: 'https'
paths:

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

基于 URL 映射生成 OpenAPI 规范

如果您的源代码中有带有 URL 映射的 REST 控制器，则可以从控制器代码快速生成 OpenAPI 规范。

  1. 单击显示 URL 的可用操作控制器路径旁边的 。

  2. 选择生成 OpenAPI 草稿。

生成 OpenAPI 操作

生成的文件保存在Scratchs and Consoles |下 OpenAPI 规范。

该操作也可在端点工具窗口中使用，您还可以在其中为整个模块生成 OpenAPI 规范。

从单独的文件引用定义

借助 OpenAPI 3.0，您可以使用$ref关键字引用托管在任何位置的定义。IntelliJ IDEA 为您提供路径补全、验证和快速导航。为了完成任务，IntelliJ IDEA 了解当前文件和外部文件的上下文，并建议使用指向相关元素的指针。

  1. 输入$ref关键字。

  2. 开始输入外部定义的路径。

您可以按快速导航到您引用的文件和元素。Ctrl0B

/help/img/idea/2023.2/openapi_ref.png
动图

预览 OpenAPI 规范

您可以使用集成的 Swagger UI 或 Redoc UI 预览 OpenAPI 规范。在编辑器中打开 OpenAPI 规范文件时，使用右上角的打开编辑器预览按钮和来显示或隐藏预览。仅编辑器按钮

要在 Swagger UI 和 Redoc UI 之间切换，请将鼠标悬停在预览区域上并单击切换视图。

招摇预览

水平分割编辑器和预览

默认情况下，编辑器和预览是垂直分割的（并排），这对于宽显示器来说很方便。您还可以水平分割，使预览显示在编辑器的下部，这样更方便纵向显示。

  • 在编辑器右上角，单击编辑器和预览按钮 编辑器和预览以水平打开编辑器和预览窗格。

    图标应更改为编辑器和预览按钮。

添加远程OpenAPI规范

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

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

要从自托管SwaggerHub 本地实例添加 OpenAPI 规范，请指定实例的 URL。

比较 OpenAPI 规范

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

根据 OpenAPI 规范生成代码

当您打开有效的 OpenAPI 规范时，IntelliJ IDEA 建议从中生成代码：

根据OpenAPI规范生成代码

单击运行按钮装订线并选择Run 'openapi file'。IntelliJ IDEA 在指定位置生成源代码文件，并显示一条通知，其中包含打开文件或将它们作为单独模块导入项目的选项。

笔记

IntelliJ IDEA 可以根据最流行语言的 OpenAPI 规范生成代码，其中包括 Java、Kotlin、JavaScript、TypeScript、Python、PHP、Go、C#、C++、C 等。有关受支持语言的完整列表，请参阅OpenAPI Generator 文档。

Swagger Codegen 运行配置

当您首次为特定文件运行代码生成时，IntelliJ IDEA 会创建OpenAPI/Swagger Code Generator 运行配置。要修改运行配置，请打开Run | 编辑配置并选择必要的配置，或者单击运行按钮装订线并选择修改运行配置。

您可以在OpenAPI/Swagger 代码生成器运行配置的顶部配置以下常用选项：

姓名

指定运行配置的名称，以便在编辑或运行时快速识别它。

允许多个实例

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

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

存储为项目文件

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

默认情况下，它是禁用的，IntelliJ IDEA 将运行配置设置存储在.idea/workspace.xml中。

常规设置

如果某些设置被隐藏，请单击“修改选项”以显示它们。

物品

描述

规格路径

OpenAPI 规范的路径。

输出目录

生成文件的目录路径。

代码生成器

选择代码生成器的类型。

语言

生成代码的目标语言。

JRE

用于运行 Swagger Codegen 的 Java 运行时

自定义模板路径

包含Mustache 模板的目录的路径。

发电参数

根据目标语言提供配置参数。有关更多信息，请参阅swagger-codegen/README.md。

在 HTTP 客户端中测试您的 OpenAPI 规范

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

创建到端点的 HTTP 请求

  • 在 OpenAPI 规范文件中，单击在 HTTP 客户端中打开按钮端点定义旁边的编辑器装订线。

  • 或者，打开查看 | 工具窗口 | 端点，右键单击端点，然后选择在 HTTP 客户端中生成请求。

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

如果您想要快速向端点发送请求并且不想保存它，可以使用端点工具窗口中的HTTP 客户端选项卡。

IntelliJ IDEA 根据可用的 OpenAPI 规范提供请求 URL 和请求正文（JSON 格式）的补全。这不仅适用于本地，也适用于远程规范（将它们添加到 IDE 设置中以启用完成功能）。

/help/img/idea/2023.2/openapi_body_completion.png
动图

重命名端点及其用途

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

  1. 执行以下任一操作：

    • 在 OpenAPI 规范文件中，将插入符号放在要重命名的端点的定义处。

    • 在 HTTP 请求文件中，将插入符号放在要重命名的 URL 路径段处。

  2. 选择重构 | 从主菜单或上下文菜单重命名，或按。ShiftF6

  3. 在打开的“重命名”对话框中，指定新端点的名称。

  4. 预览并应用更改。

IntelliJ IDEA 将重命名端点及其用法。