一 简介
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)
*内部人员（绿山墙注）