如何在 Gradle 中为 OpenAPI 3.0 使用 Swagger Codegen？

Posted 2023-02-19

【中文标题】如何在 Gradle 中为 OpenAPI 3.0 使用 Swagger Codegen？

【英文标题】：How to use Swagger Codegen in Gradle for OpenAPI 3.0?

【发布时间】：2020-05-09 13:39:09

【问题描述】：

我有一个 OpenAPI 3.0 规范（YAML 格式），并且想为 API 生成 Java 代码。我想将此作为自动化构建的一部分（最好使用 Gradle），这样我就可以创建服务接口，并将接口的实现作为自动化过程的一部分。

这个工作示例展示了如何执行此操作，但它使用 Swagger 2.0 规范 YAML：https://github.com/galovics/swagger-codegen-gradle/tree/first-server-side

我已经分叉了这个示例并添加了一个 OpenAPI 3.0 规范，但是它无法构建：https://github.com/robjwilkins/swagger-codegen-gradle/tree/openapi_v3_test

错误是：

未能读取资源列表 com.fasterxml.jackson.core.JsonParseException：无法识别的令牌 'openapi'：期待（JSON 字符串、数字、数组、对象或令牌 'null'、'true' 或 'false'）在 [Source: (String)"openapi: 3.0.0

（公关显示更改：https://github.com/robjwilkins/swagger-codegen-gradle/pull/1/files）

我的理解是需要更新的代码在build.gradle:

buildscript 
    repositories 
        mavenCentral()
    
    dependencies 
        classpath("io.swagger.codegen.v3:swagger-codegen:3.0.16")
    

可能io.swagger.codegen.v3:swagger-codegen:3.0.16 无法识别 OpenAPI 3.0？

Swagger Core v3 项目似乎专注于从代码（而不是来自规范的代码）生成 YAML/JSON 规范：https://github.com/swagger-api/swagger-core

任何有关此问题的帮助将不胜感激。谢谢:)

【问题讨论】：

是的，Swagger Codegen 2.x 仅适用于 OAS2。您需要使用 Codegen 3.x。如果将类路径更改为 io.swagger.codegen.v3.swagger-codegen:3.0.16 是否有效？

我从哪里获得这种依赖关系？似乎不在 mavenCentral 中？谢谢！

mvnrepository.com/artifact/io.swagger.codegen.v3/…。之前的评论应该是io.swagger.codegen.v3:swagger-codegen:3.0.16（我打错了）。

现在得到图书馆了，谢谢。仍然出现错误：未能读取资源列表 com.fasterxml.jackson.core.JsonParseException：无法识别的令牌“openapi”：期待（JSON 字符串、数字、数组、对象或令牌“空”、“真”或“假” ) 有什么想法吗？

看起来代码或其他一些依赖项需要 OAS2 文件并且无法解析 OAS3。您是否也将imports 从io.swagger.codegen.NNN 更新为io.swagger.codegen.v3.NNN？

【参考方案1】：

我现在已经搞定了（感谢@Helen 的帮助）

所需的编辑在 build.grade 中。

首先我必须修改构建脚本以引入不同的依赖项：

buildscript 
    repositories 
        mavenCentral()
    
    dependencies 
        classpath('io.swagger.codegen.v3:swagger-codegen-maven-plugin:3.0.16')
    

改变一些导入：

import io.swagger.codegen.v3.CodegenConfigLoader
import io.swagger.codegen.v3.DefaultGenerator
import io.swagger.codegen.v3.ClientOptInput
import io.swagger.codegen.v3.ClientOpts
import io.swagger.v3.parser.OpenAPIV3Parser

并更新 generateServer 任务：

ext.apiPackage   = 'com.example.api'
ext.modelPackage = 'com.example.model'

task generateServer 
    doLast 
        def openAPI = new OpenAPIV3Parser().read(rootProject.swaggerFile.toString(), null, null)
        def clientOpts = new ClientOptInput().openAPI(openAPI)
        def codegenConfig = CodegenConfigLoader.forName('spring')
        codegenConfig.setOutputDir(project.buildDir.toString())
        clientOpts.setConfig(codegenConfig)
        def clientOps = new ClientOpts()
        clientOps.setProperties([
                'dateLibrary'     : 'java8', // Date library to use
                'useTags'         : 'true',  // Use tags for the naming
                'interfaceOnly'   : 'true'   // Generating the Controller API interface and the models only
                'apiPackage'       : project.apiPackage,
                'modelPackage'     : project.modelPackage
        ])
        clientOpts.setOpts(clientOps)

        def generator = new DefaultGenerator().opts(clientOpts)
        generator.generate() // Executing the generation
    

更新的build.gradle 在这里：https://github.com/robjwilkins/swagger-codegen-gradle/blob/openapi_v3_test/user-service-contract/build.gradle

【讨论】：

太棒了，这帮助我更进一步，我现在在创建 DefaultGenerator 时遇到了空指针的问题。我使用了额外的属性。

好的，我看到了更新，我仍然得到 NullPointer，不知道为什么，我的代码和你的一样。使用 gradle 4.9

我想通了，你的代码帮了很多忙 :) 谢谢 :) :)

这篇文章帮助解决了我的问题。是否有禁用生成 API 测试的选项？ “apiTests=false”没有像文档github.com/swagger-api/swagger-codegen中提到的那样工作