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