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

Question

我正在尝试通过 gradle 插件测试 openapi 代码生成器。所以，我有带有文档的 .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 和@Api 注释的生成接口，实现了其中的一些，但是在/swagger-ui.html 上我看不到标签。就像，当我运行未实现的请求时，我得到“未实现”状态，但我看不到正确的 ui - 它看起来是自动生成的，就像你没有在方法上使用任何招摇的注释时一样。我只能认为我搞砸了一些依赖项，但无法真正得到线索。

Answer 1

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

生成的 openapi 3 注释支持即将推出，但无论如何，简而言之，您应该自己完成缺少的注释和必要的 bean，但是这种方式很难将生成的 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