Swagger自定义模板

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