在前文《对外Restful API接口平台的设计与实现》我们设计好了API，这些API最终交付给第三方开发公司（你提供的是一个类似开放平台）或公司内部的前端人员（你编写的是一个项目的后台服务，采用动静态分离）使用，那么后续我们就要考虑如何方便终端用户（第三方开发者或前端人员）使用呢，当然需要给这些API生成文档，标注下每个API的用户，并且能在这个平台上测试这些API，这时候SwaggerUI就要大显身手了，不管你是基于SpringBoot还是自己的Web框架，它都能帮到你，以下文章以SpringBoot为例，考虑以下几个问题：
在平台上生成各个接口的使用文档，并且可以归类；
应该支持markdown语法，以便我们更好的描述接口以及使用范围等；
平台上应该能支持接口的调测，建立白名单机制，以便在API文档的Web页不需要进行验签；
文档的生成应该是与代码无关的，可基于Java注解；
回归正题，下文给出以SpringBoot为例，解决上述问题：
首先我们解决屏蔽掉API文档平台（以下简称文档网）的验签，我们可以建立白名单机制，只要接口调用的来源方是文档网，我们就在切面里自动过滤掉验签：
如上代码，只需在环绕通知里，加个判断就可以，这样我们就能在文档网里测试所有接口了；
要在一个SpringBoot项目里生成文档，我们只需要加入Swagger的maven依赖就可以了，如下：
1<properties>
2 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
3 <swagger.version>2.9.2</swagger.version>
4</properties>
5<dependencies>
6 <dependency>
7 <groupId>io.springfox</groupId>
8 <artifactId>springfox-swagger2</artifactId>
9 <version>${swagger.version}</version>
10 </dependency>
11<!--如果不需要提供生成HTML网站，可以不用以下引入-->
12 <dependency>
13 <groupId>io.springfox</groupId>
14 <artifactId>springfox-swagger-ui</artifactId>
15 <version>${swagger.version}</version>
16 </dependency>
17</dependencies>
定义一个@Configuration的Spring依赖注入，初始化Swagger：
1@Configuration
2@EnableSwagger2
3public class SwaggerConfig {
4 @Bean
5 public Docket createRestApi() {
6 Predicate<RequestHandler> predicate = new Predicate<RequestHandler>() {
7 @Override
8 // 哪些类和方法需要生成文档
9 public boolean apply(RequestHandler input) {
10 Class<?> declaringClass = input.declaringClass();
11 if (declaringClass == BasicErrorController.class)// 排除
12 return false;
13 if(declaringClass.isAnnotationPresent(RestController.class) && declaringClass.isAnnotationPresent(ApiLevel.class))
14 return true;
15 if(input.isAnnotatedWith(ResponseBody.class) && input.isAnnotatedWith(ApiLevel.class))
16 return true;
17 return false;
18 }
19 };
20 return new Docket(DocumentationType.SWAGGER_2)
21 .apiInfo(apiInfo())
22 .useDefaultResponseMessages(false)
23 .select()
24 .apis(predicate)
25 .build();
26 }
27
28 private ApiInfo apiInfo() {
29 return new ApiInfoBuilder()
30 .title("宁波公司对外API服务")
31 .description("宁波对外Restful API服务：\r\n"
32 + "- 接口的调用必须先申请高级API权限，请发邮件至 jacon.xue@sumscope.com 说明使用范围、用途等\r\n"
33 + "- 所有接口必须经过验签，[点击这里查看详情](http://doc.sumslack.com/index.php?s=/5&page_id=122)")
34 .termsOfServiceUrl("http://www.sumslack.com")
35 .contact(new Contact("NBTeam","http://www.sumslack.com","jacon.xue@sumscope.com"))
36 .version("1.0.0")//版本
37 .build();
38 }
39}
给Controller的接口方法添加注解，以便生成文档，如以下是获取债券详情的接口文档说明：
1 @RequestMapping(value="/detail/{bondKey}",method= {RequestMethod.GET})
2 @PostMapping("/detail/1.0.0/{bondKey}")
3 @ApiLevel(level=2)
4
5 @ApiOperation(value="获取债券详情", notes=DubboVersion.LEVEL_2 + "获取债券详细信息，包括剩余期限，全称等几十个信息")
6 @ApiImplicitParam(name = "bondKey", value = "债券唯一内部ID", required = true, paramType = "path",dataType="String",defaultValue="Z0000902014CORCSP01")
7 @ApiResponses(value = {
8 @ApiResponse(code = 200, message = "成功",response=BondBean.class),
9 @ApiResponse(code = 404, message = "找不到债券")})
10 public ResponseEntity<?> detail(@PathVariable String bondKey) {
11 ......
12 return ResponseEntity.ok(detail);
13 }
以下是SwaggerUI注解的使用说明：
使用SwaggerUI2生成文档
@Api
：用在接口类上，通过tags可以将接口归类@ApiOperation
：用在接口类对应的方法上，说明方法的用途、作用
value=说明方法的用途、作用
notes=方法的备注说明，支持MD@ApiImplicitParams
：用在接口类的方法上，有多个参数说明时使用`@ApiImplicitParam`：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body：@RequestBody
· form：不常用
dataType：参数类型，默认string，其它值dataType="integer"
defaultValue：参数的默认值@ApiResponses
：用在请求的方法上，表示一组响应@ApiResponse
：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类@ApiModel
：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）@ApiModelProperty
：用在属性上，描述响应类的属性
以下文章可能对你有用：
长按识别二维码关注我们
