SpringBoot 集成 Swagger3

一、快速实现

1.1、导入 Maven 依赖

<!-- SpringBoot 和 Swagger 的整合包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

1.2、直接在 SpringBoot 启动类上添加 @EnableOpenApi 注解

@SpringBootApplication
@EnableOpenApi  // 开启 Swagger 功能，必选
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

1.3、启动项目，尝试访问："/swagger-ui/" 或 “/swagger-ui/index.html”

二、深入了解 Swagger，并简单实现

2.1、创建一个 Swagger 的 JavaConfig 类，进行简单配置

@Configuration
public class SwaggerConfig {

    // Swagger 的配置信息 --> Docket
    @Bean
    public Docket docket(Environment environment) {
        // 设置要显示的环境
        Profiles profiles = Profiles.of("dev");
        // 判断是否为自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // enable()，是否启动 Swagger，如果为 false，则不能通过浏览器访问 Swagger
                .enable(flag)
                // groupName()，设置分组，参数为组名
                // 如果要分多个组，就创建多个 Docket 对象即可
                .groupName("root")
                .select()
                // RequestHandlerSelectors，配置扫描接口的方式
                // basePackage()，指定要扫描的包
                // any()，全部扫描
                // none()，不进行扫描
                // withClassAnnotation()，扫描类上面的注解，需要传递一个注解类的反射对象 XXX.class
                // withMethodAnnotation()，扫描方法上面的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                // 路径过滤，也就是指定扫描的路径
                // ant()，指定路径，可以使用通配符
                // regex()，使用正则进行过滤
                .paths(PathSelectors.ant("/**"))
                .build();
    }

    // 配置 Swagger 信息 --> ApiInfo
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger3 初步配置").version("1.0").build();
    }
}

2.2、创建实体类，并给实体类添加注释

// 给生成的文档添加注释
// @ApiModel，用于实体类上
// @ApiModelProperty，用于方法上
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("唯一标识")
    private String uuid;
    @ApiModelProperty("用户账号")
    private String username;
    @ApiModelProperty("用户密码")
    private String password;
    
	// 省略构造方法、getter 方法、 setter 方法及 toString 方法
}

2.3、创建接口层（Controller），添加注释

// 给生成的文档添加注释
// @Api，用在接口层（Controller）上，注意是 tags 属性才是注释
// @ApiOperation，用在方法上
// @ApiParam，用在参数上
@Api(tags = "路由跳转")
@RestController
public class IndexController {

    @GetMapping({"/", "/index", "/index.html"})
    public String index() {
        return "Hello swagger!";
    }

    @PostMapping("/user")
    public User user() {
        return new User();
    }

    @ApiOperation("Get 测试")
    @GetMapping("/user/get")
    public User user(@ApiParam("用户账号") String username, @ApiParam("用户密码") String password) {
        return new User(username,password);
    }

    @ApiOperation("Post 测试")
    @GetMapping("/user/post")
    public User user(@ApiParam("用户实体类") User user) {
        return user;
    }
}

2.2、重启项目，在此访问 Swagger 的路径："/swagger-ui/" 或 “/swagger-ui/index.html”