一 簡介
Swagger是一個開源項目，用於描述和生成RestAPi的文檔。可以幫助開發人員快速了解web服務的功能。
二 接入Swagger流程
1.在所在Module的pom.xml中，添加Swagger annotation 依賴
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<scope>compile</scope>
<version>
1.5
.
1
-M2</version>
</dependency>
|
2.在classpath:/templates/目錄，添加swagger maven plugin需要的模板templates.zip
3.在Controller所在Module的pom.xml文件中配置swagger maven plugin
<plugin>
<groupId>com.swagger.test</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>
3.0
.
5
</version>
<configuration>
<enable>${doc-enable}</enable> <!--注意這里 -->
<apiSources>
<apiSource>
<springmvc>
true
</springmvc> <!--是否spring mvc項目，我們的項目都填是 -->
<locations>com.swagger.web</locations><!--Controller所在包 -->
<schemes>http</schemes><!--協議 -->
<host></host><!-- 服務器地址，空值表示跟文檔是同一台機器（域名） -->
<basePath>/test</basePath><!-- api url 前綴 -->
<info>
<title>test API</title><!-- Api 標題啊 -->
<version>v1</version><!-- Api版本 -->
<description>test API的詳細描述</description><!-- Api的詳細描述 -->
<termsOfService>
http:
//www.test.com
</termsOfService>
<contact>
<email>123
@qq
.com</email><!-- 聯系人郵件 -->
<name>yourname</name><!-- 聯系人姓名 -->
</contact>
</info>
<templatePath>classpath:/templates/strapdown.html.hbs</templatePath><!-- 文檔模板 -->
<outputPath>${basedir}/src/main/webapp/doc/document.html</outputPath><!-- 文檔輸出路徑,設置在和SwaggerUI同一目錄 -->
<swaggerDirectory>${basedir}/src/main/webapp/doc/</swaggerDirectory><!-- Swagger.json輸出路徑，設置在和SwaggerUI同一目錄 -->
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
|
其中，enable如果設置為true的話，就會一直生成文檔，如果想分環境設置的話，可以在profile里配置doc-enable變量屬性實現
<profiles>
<profile>
<id>local</id>
<activation>
<activeByDefault>
true
</activeByDefault>
</activation>
<properties>
<conf-dir>local</conf-dir>
<doc-enable>
true
</doc-enable>
</properties>
</profile>
</profiles>
|
4.將Swagger UI添加到項目的web目錄下swagger_ui.zip，修改index.html文件第29行
url = "/jingquadmin/doc/swagger.json" TO url = "/yoururl/doc/swagger.json"
(另，附件中的document.html和swagger.json是插件swagger maven plugin自動生成的，添加與否均可)
（添加Swagger UI，主要是為了API的可視化）
5.在Controller上添加API annotation，在Controller接口上添加Swagger annotation
6.maven編譯項目，然后啟動項目或plus發布項目，鏈接如下：
http://host/basepath/doc/index.html 自動測試平台
http://host/basepath/doc/document.html API文檔
三 Swagger常用注解介紹
|
|
|
|
|---|---|---|
|
annotation
|
說明
|
屬性介紹
|
| Api | 加在Controller類上，將Controller標記為Swagger資源 | value - 名稱 description - 描述 |
| ApiOperation | 加在Controller方法上，表明這個方法是一個rest接口，一個@Api下可有多個@ApiOperation(一個Controller文件可有多個接口) | value - 接口名稱 notes - 詳細描述 response - 返回類 |
| ApiImplicitParams/ApiImplicitParam/ApiParam | 加在Controller方法上，表明這里需要隱藏的參數 | name - 參數名 value - 參數描述 defaultValue - 默認值 required - 是否必需 dataType - 數據類型 |
| ApiModel | 加在Model類上，用來描述封裝的參數對象和返回的參數對象 | description - 描述 |
| ApiModelProperty | 加在Model類的屬性上，描述參數的對象屬性 | value - 屬性描述 |
完整Annotation詳見http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotations/Api.html
其他：
SpringMVC項目也可以通過接入Springfox來自動生成API文檔，Springfox的前身是swagger-SpringMVC，一個開源的API doc框架。
注意：
在Controller文件中定義接口時，@RequestMapping注解中的method屬性是必須要設置的，否則Swagger插件不會生成對應接口信息；
@RequestMapping(value = "/v2/group", method = RequestMethod.GET)
*內部人員（綠山牆注）