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