一、前言

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

记住，最重要的，可以自动扫描接口生成文档，解决文档更新不及时问题！！！

二、springfox介绍

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，而springfox则是从这个组件发展而来。

通常SpringBoot项目整合swagger需要用到两个依赖： springfox-swagger2 和 springfox-swagger-ui ，用于自动生成swagger文档。

• springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
• springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。

三、SpringFox 3.0.0 发布

官方说明：

SpringFox 3.0.0 发布了，SpringFox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将 Controller 的方法以文档的形式展现。

新特性：

• Remove explicit dependencies on springfox-swagger2
• Remove any @EnableSwagger2… annotations
• Add the springfox-boot-starter dependency
• Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.

此版本的亮点：

• Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
• Spring Integration支持（非常感谢反馈）。
• SpringBoot支持 springfox Boot starter 依赖性（零配置、自动配置支持）。
• 具有自动完成功能的文档化配置属性。
• 更好的规范兼容性与2.0。
• 支持OpenApi 3.0.3。
• 零依赖。几乎只需要spring-plugin，swagger-core ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

兼容性说明：

• 需要Java 8
• 需要Spring5.x（未在早期版本中测试）
• 需要SpringBoot 2.2+（未在早期版本中测试）

注意：

应用主类增加注解 @EnableOpenApi ，删除之前版本的SwaggerConfig.java。

启动项目，访问地址： http://localhost:8080/swagger-ui/index.html ，注意2.x版本中访问的地址的为 http://localhost:8080/swagger-ui.html

四、Springboot整合Springfox 3.0使用

1、maven依赖添加

Maven项目中引入 springfox-boot-starter 依赖：

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-boot-starterartifactId>
    <version>3.0.0version>
dependency>

2、application.yml配置

注意：配置文件建议用yml，原因在配置类的地方说。

swagger:
  application-description: springfox swagger 3.0 整合Demo
  application-name: hahha
  application-version: 1.0
  enable: true
  try-host: http://localhost:8080

3、定义属性类SwaggerProperties读取前面配置文件内容

@Component
@ConfigurationProperties("swagger")
//ConfigurationProperties读取配置文件时，默认是ISO_8859_1编码，所以需要指定application.properties以外的配置文件，使用utf-8编码
//或者是用yaml文件名，读取yaml默认是utf-8编码
//或者是将utf8转换成ascall码放在properties配置文件中
//@PropertySource(value="classpath:application1.properties", encoding="UTF-8")
//我们这里用yaml方式
public class SwaggerProperties {
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    private Boolean enable;


    /**
     * 项目应用名
     */
    private String applicationName;


    /**
     * 项目版本信息
     */
    private String applicationVersion;


    /**
     * 项目描述信息
     */
    private String applicationDescription;


    /**
     * 接口调试地址
     */
    private String tryHost;


    public Boolean getEnable() {
        return enable;
    }


    public void setEnable(Boolean enable) {
        this.enable = enable;
    }


    public String getApplicationName() {
        return applicationName;
    }


    public void setApplicationName(String applicationName) {
        this.applicationName = applicationName;
    }


    public String getApplicationVersion() {
        return applicationVersion;
    }


    public void setApplicationVersion(String applicationVersion) {
        this.applicationVersion = applicationVersion;
    }


    public String getApplicationDescription() {
        return applicationDescription;
    }


    public void setApplicationDescription(String applicationDescription) {
        this.applicationDescription = applicationDescription;
    }


    public String getTryHost() {
        return tryHost;
    }


    public void setTryHost(String tryHost) {
        this.tryHost = tryHost;
    }
}

4、定义配置类，提供Docket实例

@EnableOpenApi
@Configuration
public class SwaggerConfig {


    private final SwaggerProperties swaggerProperties;


    public SwaggerConfig(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")
                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(swaggerProperties.getEnable())
                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())
                // 接口调试地址
                .host(swaggerProperties.getTryHost())
                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //指定package下的请求路径
//                .apis(RequestHandlerSelectors.any()) //任意请求路径
                .build()
                .groupName("测试swagger系统")
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http"))
                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(securitySchemes())
                // 授权信息全局应用
                .securityContexts(securityContexts());
    }


    @Bean
    public Docket createRestApi2() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")
                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(swaggerProperties.getEnable())
                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())
                // 接口调试地址
                .host(swaggerProperties.getTryHost())
                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .groupName("测试swagger2系统")
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http"))
                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(securitySchemes())
                // 授权信息全局应用
                .securityContexts(securityContexts());
    }


    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
                .description(swaggerProperties.getApplicationDescription())
                .contact(new Contact("lighter", null, "123456@gmail.com"))
                .version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
                .build();
    }


    /**
     * 设置授权信息
     */
    private List securitySchemes() {
        ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }


    /**
     * 授权信息全局应用
     */
    private List securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                        .build()
        );
    }


    @SafeVarargs
    private final <T> Set newHashSet(T... ts) {
        if (ts.length > 0) {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }
}

5、在接口中，添加接口说明

import io.swagger.annotations.*;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;


import javax.validation.Valid;
import javax.validation.constraints.*;


import java.util.ArrayList;
import java.util.List;


@Api(tags = "用户管理")
@RestController
public class UserController {


    @ApiOperation("创建用户")
    @PostMapping("/users")
    public User create(@RequestBody @Valid User user) {
        return user;
    }


    @ApiOperation("用户详情")
    @GetMapping("/users/{id}")
    public User findById(@PathVariable Long id) {
        return new User("bbb", 21, "上海", "aaa@bbb.com");
    }


    @ApiOperation("用户列表")
    @GetMapping("/users")
    public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
                           @ApiParam("每页多少条") @RequestParam int pageSize) {
        List<User> result = new ArrayList<>();
        result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
        result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
        return result;
    }


    @ApiIgnore
    @DeleteMapping("/users/{id}")
    public String deleteById(@PathVariable Long id) {
        return "delete    user    :    " + id;
    }


}


@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户基本信息")
class User {
    @ApiModelProperty("姓名")
    @Size(max = 20)
    private String name;
    @ApiModelProperty("年龄")
    @Max(150)
    @Min(1)
    private Integer age;
    @NotNull
    private String address;
    @Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+#34;)
    private String email;
}

一些常用注解说明

• @Api：用在controller类，描述API接口
• @ApiOperation：描述接口方法
• @ApiModel：描述对象
• @ApiModelProperty：描述对象属性
• @ApiImplicitParams：描述接口参数
• @ApiResponses：描述接口响应
• @ApiIgnore：忽略接口方法