Spring boot集成Swagger3

一、导入依赖

这里以springfox来使用：SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

swagger3只需要导入一个依赖：

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

二、基本使用

1.开始使用

在spring boot主类上标注@EnableOpenApi，浏览器访问http://localhost:8080/swagger-ui/即可访问到初始页面：

2.配置类的编写

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket desertsApi(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.deserts.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("desertsGroup")
                .enable(true);
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger3测试文档")
                .description("文档描述信息")
                .contact(new Contact("deserts", "#", "2569509245@qq.com"))
                .version("1.0")
                .build();
    }
}

对应配置的结果：

3.常用注解

swagger3的注解与swagger2相差很多，也兼容了swagger2的注解，区别如下：

标注在实体类上：

@Data
@ApiModel(value = "用户类",description = "用户")
public class User {
    @Schema(description = "用户名")
    private String username;
    @Schema(description = "密码")
    private String password;
}

标注在控制器上：

@RestController
@Api(tags = "用户信息处理")
public class HelloController {
    @GetMapping("/user")
    @Operation(summary = "获取用户信息")
    @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名"),
            @ApiImplicitParam(name = "password", value = "密码")})
    public User getUser(@RequestParam("username")String username, @RequestParam("password")String password){
        User user = new User();
        user.setUsername(username);
        user.setPassword(password);
        return user;
    }
}

这里的@Paramters和@Parameter注解竟然不生效，具体原因找了挺久也没有结果，有知道的朋友欢迎补充！

标注后的结果：

三、使用knife4j优化体验

1.导入依赖

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

2.访问

直接访问http://localhost:8080/doc.html

导出文档：

这样真的舒服了：

四、参考博客

Swagger3 注解使用（Open API 3）

Swagger3配置