SpringBoot整合使用Swagger

Swagger 是一个用于生成、描述、调用和可视化 RESTful Web 服务的工具。它使用 OpenAPI 规范，可以帮助开发者设计、构建、记录和使用 REST APIs。下面是如何在 Spring Boot 项目中集成 Swagger 的简单教程。

1. 添加依赖

在pom.xml文件中添加 Swagger相关依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
<!-- swagger增强ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

2.配置swagger

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.practice"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My Swagger API")
                .description("SpringBoot整合Swagger")
                .version("1.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

Docket 是 Springfox 提供的一个主要的 Swagger 配置接口，用于配置和生成 Swagger 文档。在 Spring Boot 中配置 Swagger 时，Docket 提供了多种方法和参数，用于配置Swagger文档

• select()
  • 返回一个ApiSelectorBuilder，用于控制哪些接口暴露给Swagger
• apis()
  • 用于选择哪些接口会被包含在Swagger文档中
  • RequestHandlerSelectors.any()：包含所有接口。
  • RequestHandlerSelectors.none()：不包含任何接口。
  • RequestHandlerSelectors.basePackage(String)：根据包名选择接口。
  • RequestHandlerSelectors.withClassAnnotation(Class<? extends Annotation>)：根据类上的注解选择接口。
  • RequestHandlerSelectors.withMethodAnnotation(Class<? extends Annotation>)：根据方法上的注解选择接口。
• paths()
  • 用于选择哪些路径的接口会被包含在Swagger文档中
  • PathSelectors.any()：包含所有路径。
  • PathSelectors.none()：不包含任何路径。
  • PathSelectors.regex(String)：根据正则表达式选择路径。
• apiInfo()
  • 用于设置API的一些描述信息：标题、描述、版本等
• useDefaultResponseMessages(boolean)
  • 是哦福使用默认的HTTP相应消息。默认情况下，Swagger会为每个HTTP方法生成一组默认的相应消息。
• enable(boolean)
  • 是否启用Swagger；主要用于在不同的环境中启用/禁用Swagger
• groupName(String)
  • 用于设置API文档的组名；用组名将多个Docket分组，从而生成不同的API文档。

3.接口添加注解

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理相关接口")
public class UserController {

    @PostMapping("/save")
    @ApiOperation("新增用户")
    public APIResponse<Boolean> addUser() {
        return new APIResponse<>(true);
    }

    @DeleteMapping()
    @ApiOperation("删除指定用户")
    public APIResponse deleteUser() {
        return new APIResponse<>(true);
    }

    @PutMapping()
    @ApiOperation("修改指定用户信息")
    public APIResponse updateUser() {
        return new APIResponse<>(true);
    }

    @GetMapping()
    @ApiOperation("根据用户ID获取指定用户信息")
    @ApiImplicitParam(name = "userId", value = "用户ID", defaultValue = "1", required = true)
    public APIResponse getUser(@RequestParam int userId) {
        return new APIResponse<>(true);
    }
}

swagger中有很多供使用的注解，我们在上面的代码中用到了其中的三个注解，使得swagger能够识别我们的接口

• @Api：
  • 作用在类上，用来描述当前controller中的API，通过tags属性来对API进行分类，结合swagger生成美观易懂的文档
• @ApiOperation：
  • 用来标记一个方法，并进行说明
• @ApiImplicitParam：
  • 描述方法参数的详细信息，包括参数名、类型、位置、是否必须等，主要属性如下
    • name：参数名称，必填项
    • value：参数的简单描述，可选项
    • dataType：数据类型，必填项
    • paramType：参数类型（path、query、body、header、form），必填项
    • example：示例值，可选项
    • required：参数是否必须，可选项
    • defaultValue：默认值，若请求入参没有该参数的值，则使用defaultValue，可选项

4.使用Swagger文档

启动项目，访问http://localhost:8080/swagger-ui.html#/，可以看到这样的画面，接着就可以在这个页面对接口进行调试了