Swagger-Codegen使用详解

阎麒

2023-12-01

Swagger-Codegen使用

1. 是什么

swagger 是什么应该不需要介绍。swagger-Codegen是同一团队维护的开源项目，官方介绍如是：

Swagger Codegen can simplify your buildx process by generating server stubs and client SDKs for any API, defined with the OpenAPI (formerly known as Swagger) specification, so your team can focus better on your API’s implementation and adoption.

大致就是一个代码生成器，可以基于根据Swagger定义的RESTful API可以自动生成服务端和客户端代码。其实也就是基于Json。

2. 做什么

那这个“代码生成器”可以做什么呢，其实是有点像在反向生成“代码”。不过真是用途是在多端开发时，当建立了Rest接口，就可以借此生成对应的多语言、多风格的客户端代码了。

我的用处就是在基于JSON方向生成Java服务器端代码。

3. 怎么用

单纯使用的话，最简单的方式就是下载jar,之后就可以通过Java命令java -jar 来运行。

对于 MacOS ,可通过 HomeBrew 安装 brew install swagger-codegen,之后直接使用如下命令：

swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/

如果是下载的 jar 首先可以使用：

java -jar swagger-codegen-cli-x.x.x.jar help generate

来查询帮助信息。也可以查看Swagger Codegen支持的具体某个语言的使用帮助，拿java举例：

java -jar swagger-codegen-cli-2.2.1.jar config-help -l java

下面是实例命令，列举出常用参数。

java -jar swagger-codegen-cli-xxx.jar generate -i {yourSwaggerJsonPath} -l java -o {yourOutputPath} -c {configPath} -t {templatePath}

-i : 指定swagger描述文件的路径, url地址或路径
-l: 指定生成客户端代码的语言,该参数为必须
-o: 指定生成文件的位置(默认当前目录)
-t: 指定模版文件所在目录（可选，代码生成基于jmustache,可以指定自定义模板文件）
-c: json格式的配置文件的路径;文件为json格式,支持的配置项因语言的不同而不同

配置文件根式如下：

{
  "library": "spring-boot", // 模板，对于spring 默认spring-boot  
  "developerName": "xx",
  "developerEmail": "xx",
  "developerOrganization": "albani.com",
  "invokerPackage": "com.xx.service",
  "modelPackage": "com.xx.service.data.entity", // 模型类路径
  "apiPackage": "com.xx.service.data.api",    // 接口类路径
  "artifactId": "swagger-petstore-retrofit2"
}

选择性生成

可以使用 -D来选择性生成文件

# generate only models
java ... -Dmodels {opts}
# generate only apis
java ... -Dapis {opts}
# generate only supporting files
java ... -DsupportingFiles
# generate models and supporting files
java ... -Dmodels -DsupportingFiles

对于具体使用和其余配置，在 github 页面有详细的介绍及具体参数配置，可前往阅读：swagger-Codegen。

4. 自定义

以上下载 jar, 运行命令后就可以生成代码了，但一般而言开发风格和规范总有些不同，那么其也提供了自定义功能。首先不要忘了去swagger-Codegen clone.

4.1 jmustache 模板自定义

swagger-Codegen 基于jmustache 模板映射生成代码, 位于： modules/swagger-codegen/src/main/resources/{your-language}. 简单来说就是映射：通过匹配传入的 Map 的key，进行赋值和判断等。如下：

@Controller
{{#operations}}
public class {{classname}}Controller implements {{classname}} {
 ...

可以自己在同级目录新建文件夹，新建一套模板文件，通过 -t指定。具体语法可前往 jmustache 查阅，这里不再赘述。不过这里实际自定义的主要是代码的风格，如果想增加如{classname1}元素，修改{classname}元素的默认逻辑等就要编写自定义生成类了。

4.2 自定义生成类

在modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/，每个语言都有一套自己的解析类。

自定义有多种方式，以 spring 为例, 其对应的解析类为：SpringCodegen.

你可以直接修改SpringCodegen或其父类，但这样是不规范的，不推荐
可以继承该类，或其父类来重写。推荐这种方式。

如你新建了 YourJavaCodegen类继承于AbstractJavaCodegen,那么在生成时可使用下方命令来指定解析类。

 java ... -l com.xxx.swagger.codegen.YourJavaCodegen ...

为了方便，你可以在 META-INF/services/io.swagger.codegen.CodegenConfig中加入你的自定义类，且在自定义类中重写 getName方法

@Override
public String getName() {
    return "YourSpring";
}

这样就可以像官方模板一样直接使用名称了

 java ... -l YourSpring ...

基本通过自定义解析类，大部分自定义需求都可以实现

4.3 添加自定义变量

io.swagger.codegen.CodegenParameter包含 jmustache解析时的key，可以修改添加。

io.swagger.codegen.CodegenConstants包含 config.json的配置，可以增加配置项。

4.4 编译

swagger-codegen 是一个 Maven 管理的项目，以上修改后可以通过 package/ install 命令重新生成 jar 使用。

当然也可以自己建立一个项目，添加 swagger-codegen 的依赖，再做相关自定义开发，最后打包。

5. 怎么接入

以上是基于 jar 的于终端中运行，如果需要接入项目，则需要引入依赖。

对于 Java 服务器端开发来说，一般项目项目管理基于 Maven 或 Gradle。以下对两者分别说明。

Maven: pom文件中添加如下:

 <plugin>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-codegen-maven-plugin</artifactId>
   <version>2.3.1</version>
   <executions>
       <execution>
           <goals>
               <goal>generate</goal>
           </goals>
           <configuration>
               <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
               <language>java</language>
               <configOptions>
                  <sourceFolder>src/gen/java/main</sourceFolder>
               </configOptions>
           </configuration>
       </execution>
   </executions>
</plugin>

由于我基于 Gradle 管理，未基于Maven实践详细配置可参考swagger-codegen-maven-plugin

Gradle:

plugins {
  id 'org.hidetake.swagger.generator' version '2.18.1'
}

repositories {
  jcenter()
}

dependencies {
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.2'             // Swagger Codegen V2
  ...// or Swagger Codegen V3  ...// or OpenAPI Generator
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
      components = ['models', 'apis']
      templateDir = file('path')
      outputDir = file("${projectDir}/xxx")
    }
  }
}

对于版本较老的可以使用以下方式引入 plugin：

dependencies {
    classpath "gradle.plugin.org.hidetake:gradle-swagger-generator-plugin:2.18.1"
}
apply plugin: "org.hidetake.swagger.generator"

对于 dependencies 如果你进行了自定义处理，可以引用私库,或本地测试如：

swaggerCodegen files('xxx/xxxSwaggerCode-cli.jar')

对于 swaggerSource,就是进行相关配置。可以指定 config.json 进行详细配置。

之后运行 ./gradlew generateSwaggerCode 即可。

详细介绍位于：gradle-swagger-generator-plugin.

6. 源码解析

参考另一篇文章：

Swagger-Codegen使用详解