在项目中，需要对接口进行定义，生成文档，swagger是个不错的选择，使用起来也很方便
这里就来说说它的配置和使用
另外，还有raml-mocker，后期考虑在写一篇吧
第一步：pom.xml修改，引入springboot和swagger:
<!--spring boot-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<!--log4j-slf4j-impl与 logback-classic包不兼容，删除这个包 -->
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
第二步：从git上下载一个版本的swagger,地址如下：
https://github.com/swagger-api/swagger-ui/tree/v2.2.10
代码clone下来后，在本地打开，并将dist目录复制到项目中，如下：
第三步：我们配置下swagger的访问路径，添加swagger.properties,内容如下：
springfox.documentation.swagger.v2.path=/rest/api/doc
同时，修改index.html页面上请求的路径，如下：
第四步：我们添加SwaggerConfig.java，配置如下：
图中标注箭头的是主要点，限制范围在apis()中配置
第五步：我们修改WebMvcConfig.java，添加资源路径如下：
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("/rest/api/doc/**").addResourceLocations("classpath:/swagger/dist/");
super.addResourceHandlers(registry);
}
做完上述的配置，我们就可以在项目中，进行编码注解了，重点使用如下：
@Api 描述接口对主要用途
@Log4j2
@RestController
@RequestMapping(value="/api/users", produces = MediaType.APPLICATION_JSON_VALUE)
@Api(description = "用户管理")
public class AdminController extends BaseController{
@ApiOperation 描述方法对用处
@ApiImplicitParam 在方法上对参数进行描述，这里是对象，参照dataType
另外还有@ApiImplicitParams
@ApiOperation(value = "保存用户信息",notes = "添加、修改用户基础信息")
@ApiImplicitParam(name="user",value = "用户对象实体",required = true,dataType = "User")
@PostMapping(value ="/save")
public JsonResult create(@RequestBody User user) {
@ApiParam 请求参数属性的描述
@ApiOperation(value = "删除一个用户",notes = "根据编号删除用户信息")
@DeleteMapping(value ="/delete/id/{id}")
public JsonResult delete(@ApiParam(value = "编号",required = true)
@PathVariable String id) {
实体对象对属性添加描述，可以使用：
@ApiModelProperty，留意hidden，该属性会在输出文档时隐藏
@ApiModelProperty(hidden=true)
@Column(name="PICTURE_ID_",nullable = true)
private String pictureId;
@ApiModelProperty(value="状态，1正常，0待审核,-1审核失败")
@Column(name = "STATE_",nullable = true)
private Integer state;
另外，还可以使用@ApiIgnore: 忽略某类/方法/参数的文档
做好上述配置后，就可以打包运行看效果了
比如，我们先使用maven执行clean package生成一个jar包
执行：java -jar admin.jar
查看log，确认启动成功后，我们打开浏览器访问如下地址：
http://localhost:8080/rest/api/doc/index.html
就可以看到效果了
