1 背景
springBoot作为微服务首选框架，为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。
swagger可以通过代码和注释自动为web项目生成在线文档，这里使用swagger。
swagger官网地址：https://swagger.io/
2 使用
2.1 maven依赖
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
依赖说明：
（1）springfox-swagger2
检测spring的web请求信息，生成检测结果（json格式）。
（2）springfox-swagger-ui
根据springfox-swagger2生成的数据，生成可视化的友好页面。
2.2 配置代码
Springfox提供Docket对象，为其设置相关属性，将其注册成为spring的bean后，可以在接口文档中展示（可配置多个Docket的bean，对应不同分组的接口）
@Configuration
@EnableSwagger2
public class Swagger2Conf {
@Bean
public Docket getUserDocket(){
ApiInfo apiInfo=new ApiInfoBuilder()
.title("用户管理")//api标题
.description("用户管理相关接口描述")//api描述
.version("1.0.0")//版本号
.contact("sabre")//本API负责人的联系信息
.build();
return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
.apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
.select()//启动用于api选择的构建器
.apis(RequestHandlerSelectors.basePackage("com.scaf.test.web.boot.controller.api"))//扫描接口的包
.paths(PathSelectors.any())//路径过滤器（扫描所有路径）
.build();
}
}
其中@Configuration、@Bean均为spring初始化bean相关的注解。@EnableSwagger2表示启用swagger2。
2.3 接口配置
通过在控制器和接口方法上加上相关注解，可以给接口和控制器添加相关的接口说明信息。
常用注解如下：
| 注解 | 使用的地方 | 用途 |
|---|---|---|
| @Api | 类/接口 | 描述类/接口主要用途 |
| @ApiOperation | 方法 | 描述方法的用途 |
| @ApiImplicitParam | 方法 | 用于描述接口的非对象参数 |
| @ApiImplicitParams | 方法 | 用于描述接口的非对象参数集 |
| @ApiIgnore | 类/方法/参数 | Swagger 文档不会显示拥有该注解的接口 |
| @ApiModel | 参数实体类 | 可设置接口相关实体的描述 |
| ApiModelProperty | 参数实体类属性 | 可设置实体属性的相关描述 |
参数实体类代码：
@ApiModel("用户")
public class UserInfo {
@ApiModelProperty("用户ID")
private Integer id;
@ApiModelProperty("用户代码")
private String userCode;
@ApiModelProperty("用户姓名")
private String userName;
@ApiModelProperty("年龄")
private Integer age;
}
接口代码：
@Api("用户管理api")
@RestController
@RequestMapping("/userApi")
public class UserApiController {
@Autowired
private UserApiService userApiService;
@ApiOperation("查询用户信息")
@PostMapping("/findUserList")
public JSONObject findUserList(){
JSONObject jsonObject=new JSONObject();
jsonObject.put("success",true);
jsonObject.put("result",userApiService.findUserList());
return jsonObject;
}
@ApiOperation("保存用户")
@PostMapping("saveUser")
public JSONObject saveUser(@RequestBody UserInfo userInfo){
userApiService.saveUser(userInfo);
JSONObject jsonObject=new JSONObject();
jsonObject.put("success",true);
jsonObject.put("message",null);
return jsonObject;
}
}
2.4 访问
启动项目后，通过以下方式访问swagger2的接口说明
http://地址:端口/应用名/swagger-ui.html
如：http://localhost:8080/swagger-ui.html
3 其他
3.1 访问swagger2接口源信息
通过如下方式访问：
http://地址:端口/应用名/v2/api-docs
如：http://localhost:8080/v2/api-docs
返回的json格式如下：
{"swagger":"2.0","info":{"description":"用户管理相关接口描述","title":"用户管理"},"host":"localhost:8080","basePath":"/","tags":[{"name":"user-api-controller","description":"User Api Controller"}],"paths":{"/userApi/findUserList":{"post":{"tags":["user-api-controller"],"summary":"findUserList","operationId":"findUserListUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"userInfo","description":"userInfo","required":true,"schema":{"$ref":"#/definitions/UserInfo"}}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":{"type":"object"}}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/userApi/saveUser":{"post":{"tags":["user-api-controller"],"summary":"saveUser","operationId":"saveUserUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"userInfo","description":"userInfo","required":true,"schema":{"$ref":"#/definitions/UserInfo"}}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":{"type":"object"}}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}}},"definitions":{"UserInfo":{"type":"object","properties":{"age":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int32"},"userCode":{"type":"string"},"userName":{"type":"string"}},"title":"UserInfo"}}}
swagger-ui通过对此源信息的解析，生成相关页面
3.2 swagger2静态资源
swagger通过webjars的方式，来实现网页方式的接口访问。
如配置拦截器、shiro、spring security等，需对以下页面放行，来保证swagger页面的正常访问：
/swagger*/**
/v2/**
/webjars/**
如下，spring拦截器，需配置如下：