欢迎使用CSDN-markdown编辑器

Swagger自定义模板

下载Swagger codegen

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-codegen-cli</artifactId>
  <version>2.2.1</version>
</dependency>

或者访问其github项目位置。

生成自定义模板项目

我们将用meta命令来生成自定义模板项目。可以先运行一下下面的命令，看看具体的参数。

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

简单说明一下参数

 -n <name>, --name <name> 
 自定义模板的名字，之后会用做swagger codegen支持的新语言名，在-l 命令中使用


 -o <output directory>, --output <output directory>
 输出目录，默认当前目录

 -p <package>, --package <package>
 输出包名，默认是 io.swagger.codegen

生成项目概述

生成的是一个maven项目，可以用mvn package生成jar文件。
项目里面只有一个java文件,为了说明方便，叫它XGenerator，是一个继承io.swagger.codegen.DefaultCodegen的生成器，里面的注释需要好好阅读以下。

简单来说，swagger生成代码的流程，是把用设计器生成的ymal或者json代码，输出到mustach模板中。那么由于json代码内容比较多，它把内容大概分为2个部分，一个是model，一个是operation。

XGenerator 继承而来的 modelTemplateFiles，是model模板，可以访问model的数据；
apiTemplateFiles就是api和controller的模板集合了，可以访问operation的数据。
此外，还有supportingFiles，可以访问所有数据。

模板可以使用的变量

也就是如何查看model和operation的内容？
运行生成命令时，加上-DdebugModels或者-DdebugOperations就可以，比如查看生成c#代码时的model和operation数据

java -DdebugModels -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l csharp \

java -DdebugOperations -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l csharp \

在调试项目时，输出还是非常有用的。

修改代码

由于我们需要改一下spring-mvc的模板，所以先要获得原来的模板内容。这些内容都在swagger-codegen项目里面。

check swagger-codegen源码

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

然后用目前最新的2.2.1版本。

git checkout v2.2.1

打开swagger-codegen项目，我们感兴趣的是spring-mvc相关的部分，找到io.swagger.codegen.languages.SpringCodegen。其他相关语言的生成，都在io.swagger.codegen.languages包下面。顺便看看SpringCodegen的父类io.swagger.codegen.languages.AbstractJavaCodegen。

然后我们去找相关的模板文件，swagger-codegen\modules\swagger-codegen\src\main\resources\JavaSpring\ 目录下面的mustach文件，都是相关的模板文件。

至于mustach模板的语法，请参见文档。

复制相关模板

复制相关模板到自定义模板项目的resource目录下面，进行你需要的更改。

修改XGenerator代码

下面我们需要改XGenerator里面的内容。

在构造方法里面，找到

apiTemplateFiles.put

这个地方，把需要的模板加入进去。

把io.swagger.codegen.languages.SpringCodegen#postProcessOperations这个方法复制到XGenerator里面。用io.swagger.codegen.languages.AbstractJavaCodegen#getTypeDeclaration的内容覆盖XGenerator里面的同名方法。
这2个处理完全是因为默认传过来的数据格式和java的集合模板符号不一致，所做的处理。详细可以看其注释，也可以用之前说的-DdebugModels或者-DdebugOperations查看原始数据。

调试

在pom.xml里面加入下面依赖项。

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-codegen-cli</artifactId>
  <version>${swagger-codegen-version}</version>
  <scope>provided</scope>
</dependency>

配置main class为io.swagger.codegen.SwaggerCodegen
参数和之前命令行一致，注意改-l 参数为自己的项目名（XGenerator#getName中返回的字符串）。

运行

修改和调试完毕之后，运行maven命令打包。

mvn package

在target目录下找到生成的jar包，假设名为x-swagger-codegen.jar。为了方便，将其复制到swagger-codegen-cli.jar 同一目录。然后执行命令来运行。

java -cp x-swagger-codegen.jar;swagger-codegen-cli.jar io.swagger.codegen.SwaggerCodegen