Swagger 代码生成

Swagger Codegen 是一个可执行 Jar 包，它可以解析 API 文档并生成不同语言的代码。

在生成代码前，请确保 API 文档内容可信，否则执行代码生成命令可能会发生代码注入危险。

使用

可以从 https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/ 获取最新的可指向 Jar 包（运行环境最低要求是 Java 8）。

这里我下载的是 https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.9/swagger-codegen-cli-2.4.9.jar 右击链接另存为即可。

华为镜像 https://repo.huaweicloud.com/repository/maven/io/swagger/swagger-codegen-cli/2.4.9/swagger-codegen-cli-2.4.9.jar

java -jar swagger-codegen-cli-2.4.9.jar help

从服务器获取 API 文档，并生成代码到 petstore-java, petstore-spring 目录：

# -i 可以指向远程地址或本地 json/yaml 文件
java -jar swagger-codegen-cli-2.4.9.jar generate 
  -i https://petstore.swagger.io/v2/swagger.json 
  -l java 
  -o petstore-java

java -jar swagger-codegen-cli-2.4.9.jar generate 
  -i https://petstore.swagger.io/v2/swagger.json 
  -l spring
  -o petstore-spring

查看生成命令支持的参数：

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

查看 spring 支持的配置项，可以通过 -c 传递配置文件：

java -jar swagger-codegen-cli-2.4.9.jar config-help -l spring

查看支持的语言：

java -jar swagger-codegen-cli-2.4.9.jar langs

模板

Swagger Codegen 使用 mustache 模板以及 jmustache 模板引擎。

首先需要下克隆下项目源码：

git clone https://github.com/swagger-api/swagger-codegen.git

编译：

cd modules\swagger-codegen-cli
mvn clean package
java -jar target\swagger-codegen-cli.jar help

定制模板的两种方式：

1. 修改下 modules/swagger-codegen/src/main/resources/${your-language} 下的模板，Java 相关目录有 Java, JavaSpring
2. 自己新建模板并使用 -t 指向模板目录

开发自己的代码生成器

Swagger Codegen 提供命令可以帮助您生成项目，包括基础的类和模板：

# -o 输出目录
# -n 生成器名称
# -p 包名
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar meta 
  -o output\myLibrary 
  -n myClientCodegen 
  -p com.liaozibo.swagger.codegen

Maven 插件

Swagger Codegen Maven 插件可以将 Swagger Codegen 集成到您的 Java 项目中。

Swagger Codegen Maven 插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-codegen-maven-plugin</artifactId>
            <version>2.3.1</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
                <language>spring</language>
                <output>${project.basedir}</output>
                <addCompileSourceRoot>true</addCompileSourceRoot>
                <modelPackage>com.liaozibo.study.swagger.model</modelPackage>
                <apiPackage>com.liaozibo.study.swagger.api</apiPackage>
                <invokerPackage>com.liaozibo.study.swagger.client</invokerPackage>
                <configOptions>
                    <sourceFolder>src/main/java</sourceFolder>
                </configOptions>
                <generateModelDocumentation>false</generateModelDocumentation>
                <generateApiDocumentation>false</generateApiDocumentation>
                <generateSupportingFiles>false</generateSupportingFiles>
            </configuration>
        </plugin>
    </plugins>
</build>

将自动生成代码加入 .gitignore：

/.idea/
/swagger-codegen.iml
/src/main/java/com/liaozibo/study/swagger/api/
/src/main/java/com/liaozibo/study/swagger/model/
/target/classes/
/target/maven-status/maven-compiler-plugin/compile/default-compile/
 

执行命令生成代码：

mvn clean compile

配置：

• inputSpec：OpenAPI 文档路径
• language：目标生成语言（java/spring）
• output：输出路径，默认是：${project.build.directory}/generated-sources/swagger
• templateDirectory：mustache 模板目录（mustache 是一个模板引擎）
• addCompileSourceRoot：将输出路径设置为 source root，默认是 true
• modelPackage：对象模型包路径
• apiPackage：API 接口包路径
• invokerPackage：调用代码包路径
• modelNamePrefix, modelNameSuffix：对象模型的前缀和后缀
• withXml：在生成的对象模型和 API 接口启用 XML 注解（仅支持 Java 语言）
• configOptions
• configHelp
• ignoreFileOverride：.swagger-codegen-ignore 的路径
• generateApis：生成 API 接口，默认是 true
• generateApiTests：生成 API 接口测试代码，默认是 true，只有 generateApis 是 true 时才有效
• generateApiDocumentation：生成 API 接口文档（Markdown 格式，在 doc 目录下），默认是 true，只有 generateApis 是 true 时才有效
• generateModels：生成对象模型
• modelsToGenerate：指定要生成的对象模型列表，以逗号分隔，默认是全部
• generateModelTests：生成对象模型测试代码，默认是 true，只有 generateModels 是 true 时才有效
• generateModelDocumentation ：生成对象模型文档，默认是 true，只有 generateModels 是 true 时才有效
• generateSupportingFiles：生成支持文件，默认是 true，除了对象模型和接口代码文件，其他都是支持文件
• supportingFilesToGenerate：指定要生成的支持文件列表，以逗号分隔，默认是全部
• skip：跳过代码生成，默认是 false，也可以通过 codegen.skip 属性设置

参阅

• 代码示例
• swagger-codegen 项目地址
• swagger-codegen Maven 插件