Swagger3

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。相比Swagger2，Swagger3使用配置更为简单和友好。

1. 依赖

<!-- swagger -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

备注：Swagger2要引入两个依赖，Swagger3只要这一个依赖。

2. 配置

package com.config.swagger;

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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class Swagger3Config {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                .select()
                //添加swagger接口提取范围,修改成指向你的controller包
                .apis(RequestHandlerSelectors.basePackage("com.demo1.controller").or(RequestHandlerSelectors.basePackage("com.demo2.controller")))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("标题")
                .description("描述")
                .contact(new Contact("MES", "", ""))
                .version("1.0")
                .build();
    }

}

备注：注意.apis扫描多个包的写法。

3. 业务代码

@RestController
@Api(tags = "UserController")
public class UserController {
    @Autowired
    UserService userService;

    @RequestMapping(method = {RequestMethod.GET},path = {"/getUserList"})
    @ApiOperation(value = "getUserList")
    public ResponseMessage<List<User>> getUserList() throws Exception {
        List<User> userList = userService.list();
        return ResponseMessage.success(userList);
    }
}

备注：
(1) 接口归档：@Api主要是Controller类上加入一个Swagger注解，描述这个Controller是哪一个模块的接口，分类明确。假如是用户的接口类。那么这个类会有对用户的增删改查不同的方法。
(2) 接口方法：大的分类标注好了，在每个方法的上面添加一个@ApiOperation注解，描述这个接口方法的功能，是删除还是修改或者添加等。

@Data
@ApiModel(value = "User", description = "")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;

    private Long id;

    @ApiModelProperty("uuid")
    @TableId(value = "uuid", type = IdType.ASSIGN_UUID)
    private String uuid;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;

    @ApiModelProperty("邮箱")
    private String email;
}

备注：
(1) @ApiModel：在实体类上边使用，标记类时swagger的解析类
(2) @ApiModelProperty：使用在被 @ApiModel 注解的模型类的属性上

4. 访问地址

http://localhost:8080/swagger-ui/index.html
备注：请注意Swagger2的区别，Swagger2访问地址为http://localhost:8080/swagger-ui.html

5. 其他设置

感觉Swagger3界面的Servers占用了界面较多的位置，有点不习惯想保留Swagger2的样式不显示Servers区域，这块资料很少，梳理实现代码参考如下：

// 清空index.html上的server显示，实现Swagger3的拦截器WebMvcOpenApiTransformationFilter
@Component
public class SpringFoxSwaggerHostResolver implements WebMvcOpenApiTransformationFilter {
    @Override
    public OpenAPI transform(OpenApiTransformationContext<HttpServletRequest> context) {
        OpenAPI swagger = context.getSpecification();
        List<Server> serverList = new ArrayList<Server>();
        swagger.setServers(serverList);
        return swagger;
    }
    @Override
    public boolean supports(DocumentationType delimiter) {
        return DocumentationType.OAS_30.equals(delimiter);
    }
}