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