​相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

而随着Springboot、Springcloud等微服务的流行，每个项目都有成百上千个接口调用，这时候再要求人工编写接口文档并且保证文档的实时更新几乎是一件不可能完成的事，所以这时候我们迫切需要一个工具，一个能帮我们自动化生成接口文档以及自动更新文档的工具。它就是Swagger。

Swagger 提供了一个全新的维护 API 文档的方式，有4大优点：

Swagger集成

集成Swagger很简单，只需要简单三步。

第一步：引入依赖包

io.springfox

springfox-swagger2

2.9.2

io.springfox

springfox-swagger-ui

2.9.2

第二步：修改配置文件

1.application.properties 加入配置

用于控制是否开启Swagger，生产环境记得关闭Swagger，将值设置为 false

springfox.swagger2.enabled = true

2.增加一个swagger配置类

@Configuration@EnableSwagger2@ConditionalOnClass(Docket.class)public class SwaggerConfig {

private static final String VERSION = "1.0";

@Value("${springfox.swagger2.enabled}")
private Boolean swaggerEnabled;

@Bean
public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(swaggerEnabled)
            .groupName("SwaggerDemo")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            .paths(PathSelectors.any())
            .build();
}

/**
 * 添加摘要信息
 */
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("接口文档")
            .contact(new Contact("JAVA日知录","http://javadaily.cn","jianzh5@163.com"))
            .description("Swagger接口文档")
            .version(VERSION)
            .build();
}

}

这里通过.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))标明给加上@Api注解的类自动生成接口文档。

第三步，配置API接口@RestController@Api(tags = "参数校验")@Slf4j@Validatedpublic class ValidController {

@PostMapping("/valid/test1")
@ApiOperation("RequestBody校验")
public String test1(@Validated @RequestBody ValidVO validVO){
    log.info("validEntity is {}", validVO);
    return "test1 valid success";
}

@ApiOperation("Form校验")
@PostMapping(value = "/valid/test2")
public String test2(@Validated ValidVO validVO){
    log.info("validEntity is {}", validVO);
    return "test2 valid success";
}

@ApiOperation("单参数校验")
@PostMapping(value = "/valid/test3")
public String test3(@Email String email){
    log.info("email is {}", email);
    return "email valid success";
}

}

通过@Api注解标注需要生成接口文档，通过@ApiOperation注解标注接口名。

同时我们给ValidVO也加上对应的注解

@Data@ApiModel(value = "参数校验类")public class ValidVO {

@ApiModelProperty("ID")
private String id;

@ApiModelProperty(value = "应用ID",example = "cloud")
private String appId;

@NotEmpty(message = "级别不能为空")
@ApiModelProperty(value = "级别")
private String level;

@ApiModelProperty(value = "年龄")
private int age;

...

}

通过@ApiModel标注这是一个参数实体，通过@ApiModelProperty标注字段说明。

Unable to infer base url

简单三步，我们项目就集成了Swagger接口文档，赶紧启动服务，访问http://localhost:8080/swagger-ui.html体验一下。

好吧，出了点小问题，不过不用慌。

出现这个问题的原因是因为我们加上了ResponseBodyAdvice统一处理返回值/响应体，导致给Swagger的返回值也包装了一层，UI页面无法解析。可以通过http://localhost:8080/v2/api-docs?group=SwaggerDemo观察Swagger返回的json数据。

既然知道了问题原因那就很好解决了，我们只需要在ResponseBodyAdvice处理类中只转换我们自己项目的接口即可。

@RestControllerAdvice(basePackages = "com.jianzh5.blog")

@Slf4j

public class ResponseAdvice implements ResponseBodyAdvice