使用swagger构建API文档有很多优点：

可以整合到代码中，在开发时通过注解，编写注释，自动生成API文档，保证文档时效性。

支持四十多种语言，具有良好的跨语言性。

可以将文档规范导入相关的工具，自动地创建自动化测试。

SwaggerUI得到的是一份可交互式的API文档，可以直接在文档页面尝试API的调用，省去了准备调用参数的过程。

生成文档

首先我们在.xml文件中引入swagger相关依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>1234567891011复制代码类型：[java]

在com.javafamily.familydemo文件下创建config文件，并在config文件下创建

SwaggerConfig.java。

package com.javafamily.familydemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

// 表示当前类为配置类
@Configuration
// 启用SwaggerAPI文档
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API")
                .description("一起看下API文档吧")
                .termsOfServiceUrl("http://www.JavaFamily.com")
                .version("V1")
                .build();
    }

    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 把根目录下的所有接口函数形成文档
                .apis(RequestHandlerSelectors.basePackage("com.javafamily.familydemo"))
                .paths(PathSelectors.regex("/.*"))
                .build();
    }
}12345678910111213141516171819202122232425262728293031323334353637复制代码类型：[java]

运行程序，在浏览器访问http://localhost:8888/swagger-ui.html

点击pets-controller

点击一个接口，里面的参数都能很详细的展示出来。

我们还可以通过tryitout来请求响应结果。

所以，API文档不仅有看的功能，还拥有调用的功能。

注解

对于全英文比较吃力的人员，swagger也支持中文的接口功能注释。

@ApiOperation(value = "添加宠物", notes = "添加一只宠物信息", tags = "Pets", httpMethod = "POST")
@ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "宠物id", required = true, dataType = "long"),
            @ApiImplicitParam(name = "name", value = "宠物名称", required = true, dataType = "String"),
            @ApiImplicitParam(name = "varieties", value = "宠物品种", required = true, dataType = "String")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "success!", response = Response.class),
    })
    @RequestMapping(value = "/pets", method = RequestMethod.POST)
    public Response savePets(@RequestBody Pets pets) {
        log.info("savePets" + pets);
        return Response.success(petsService.savePets(pets));
    }1234567891011121314复制代码类型：[java]

这样我们就拥有了中文注释。

接下来我们看一下@ApiModel注解，它能够在API文档中解释字段用处。

@Data
@ApiModel(value = "提供一个备用名")
public class Response {
    @ApiModelProperty(value="判断请求是否成功")
    private boolean isok;
    @ApiModelProperty(value="状态码")
    private int code;
    @ApiModelProperty(value="信息描述")
    private String message;
    @ApiModelProperty(value="返回数据")
    private Object data;1234567891011复制代码类型：[java]