gradle 插件的 Openapi codegen：UI 显示不正确

Question

我正在尝试通过 gradle 插件测试 openapi codegenerator。所以，我有带有文档的 .yml 文件（运行它在 https://editor.swagger.io/ 中，看起来很酷）

openapi: 3.0.2
info:
  title: Testing docs
  version: 1.0.0
tags:
  - name: Registration
paths:
  /registration:
    post:
      tags:
        - Registration
      summary: Register user
...

这是我的一部分 build.gradle

plugins {
    id "org.openapi.generator" version "5.0.1"
}

def sDir= "$buildDir/generated"
openApiGenerate {
    generatorName = "spring"
    inputSpec = "$rootDir/src/main/resources/documentation/openapi.yml"
    outputDir = "${sDir}"
    apiPackage = "generated.api"
    invokerPackage = "generated.invoker"
    modelPackage = "generated.model"
    configOptions = [
            interfaceOnly: "true",
            useTags: "true"
    ]
}
...

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-ui:1.5.2'
    implementation 'io.springfox:springfox-swagger2:3.0.0'
    implementation 'org.openapitools:jackson-databind-nullable:0.2.1'
}

我有一堆用@Tag 和@[=24= 注释生成的接口，实现了其中的一些，但是在/swagger-ui.html 上我没有看到标签。就像，当我运行没有实现请求时，我得到“未实现”状态，但我没有看到正确的 ui - 它看起来是自动生成的，就像你不使用任何 swagger 注释一样在方法上。我只能认为我搞砸了一些依赖关系，但无法真正得到线索。

Answer 1

您看到的 ui 不是从您用来生成代码的文档 .yml 文件生成的。相反，ui 是从生成的代码生成的，它有自己的注释，目前是 springfox 注释，是 swagger2 注释而不是 openapi 3 注释（尽管你的原始文件是 openapi 3）。

生成的 openapi 3 注释支持即将推出，但无论如何，简而言之，您应该必须自己完成缺少的注释和必要的 beans，但这种方式很难将生成的 openapi 定义与您的原始定义相匹配文档文件。

幸运的是有更好的选择：只需将您的 yml 文件添加到 src/main/resources/static 并将此行添加到您的 application.properties 文件：

springdoc.swagger-ui.url=/<your_file>.yml

如此处所述https://springdoc.org/#how-can-use-custom-jsonyml-file-instead-of-generated-one。你已经有 springdoc-ui 依赖，所以你不需要添加任何更多的依赖。

这将忽略您的代码注释并直接从您的文档 .yml 文件生成 ui

gradle 插件的 Openapi codegen：UI 显示不正确

Openapi codegen by gradle plugin: UI not showing correctly

spring-boot

swagger-ui

openapi