SpringBoot2.7集成Swagger3.0

摘要

本文介绍了Swagger是什么，常用注解有哪些，并编码集成到SpringBoot中使用，show codes。

Swagger是什么？常用注解都有什么？

Swagger是一个用于设计、构建、文档化和调用RESTful API的开源工具，基于OpenAPI规范。它通过注解自动生成 API 文档，并提供可视化界面供开发者测试接口。

核心功能：

1.自动生成文档：通过代码中的注解描述接口信息。

2.在线调试接口：在浏览器中直接调用接口响应。

3.规范 API 设计：确保接口符合OpenAPI标准。

4.多语言支持：支持生成客户端SDK，如Java、Python。

常用注解：

less 复制代码

//用于描述控制器类，指定模块的标签和描述。 tags: 用于指定模块的标签，这有助于在Swagger UI中对API进行分组。 description: 提供控制器的详细描述。
@Api(tags = "模块1", description = "第一个控制器的描述")

//用于描述一个方法（API操作），指定操作的名称和说明。value: 操作的简短描述。notes: 提供更详细的说明。
@ApiOperation(value = "测试接口1", notes = "返回一个文本内容")

//用于描述请求参数，可以是单个参数或多个参数。name: 参数的名称。value: 参数的描述。dataType: 参数的数据类型。paramType: 参数的位置（如查询参数、路径参数等）。
@ApiImplicitParam(name = "name", value = "姓名", dataType = "String", paramType = "query")
@ApiImplicitParams({
       @ApiImplicitParam(name = "id", value = "ID值", dataType = "Integer", paramType = "query"),
       @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", paramType = "query")
})

//用于描述方法参数的详细信息。name: 参数的名称。value: 参数的描述。defaultValue: 参数的默认值。example: 参数的示例值。required: 参数是否必需。
@ApiParam(name = "id", value = "需要传递的ID值", defaultValue = "1", example = "1", required = true)

//用于描述模型类及其属性。value: 模型的名称。description: 模型的描述。example: 提供属性的示例值。required: 属性是否必需。
@ApiModel(value = "请求1", description = "请求体1")
@ApiModelProperty(value = "用户名", example = "oakwang", required = true)

//在SpringDoc OpenAPI（Swagger 3.x）中，@Schema 用于描述模型属性。description: 属性的描述。example: 属性的示例值。required: 属性是否必需。
@Schema(description = "用户名", example = "oakwang", required = true)

SprinBoot集成swagger3.0编码测试

引入依赖：

xml 复制代码

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

定义启动类：

arduino 复制代码

package org.coffeebeans;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * <li>ClassName: SwaggerApplication </li>
 * <li>Author: OakWang </li>
 * <li>Version: V1.0</li>
 */
@Slf4j
@SpringBootApplication
public class SwaggerApplication {

    public static void main(String[] args) {
       SpringApplication springApplication = new SpringApplication(SwaggerApplication.class);
       springApplication.run(args);
       log.info("SwaggerApplication start success!");
    }

}

配置swagger初始化配置参数：

kotlin 复制代码

package org.coffeebeans.config;

import org.springframework.beans.factory.annotation.Value;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * <li>ClassName: SwaggerConfig </li>
 * <li>Author: OakWang </li>
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    private boolean enabled;

    @Bean
    public Docket api() {
       return new Docket(DocumentationType.OAS_30)
             .enable(enabled)// 是否启用
             .apiInfo(apiInfo())
             .select()
             .apis(RequestHandlerSelectors.basePackage("org.coffeebeans.controller")) //指定要扫描的控制器包路径。
             .paths(PathSelectors.any()) //指定要扫描的路径，这里表示扫描所有路径。
             .build();
    }

    private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
             .title("我的swagger文档") //标题
             .description("这是一个用作接口管理的swagger文档") //描述
             .version("1.0.0") //版本
             .contact(new Contact("作者名", "联系网址", "联系邮箱"))
             .build();
    }
}

处理swagger3.0启动报错，application.properties：

ini 复制代码

##### 端口 #####
swagger-use.port=12001

# 强制使用旧版路径匹配策略
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

写api接口：

less 复制代码

package org.coffeebeans.controller;

import io.swagger.annotations.*;
import org.coffeebeans.entity.Request1;
import org.coffeebeans.entity.Request2;
import org.springframework.web.bind.annotation.*;

/**
 * <li>ClassName: MyController1 </li>
 * <li>Author: OakWang </li>
 */
@Api(tags = "模块1", description = "第一个控制器的描述")
@RestController
@RequestMapping("/module1")
public class MyController1 {

    @ApiOperation(value = "测试接口1", notes = "返回一个文本内容")
    @GetMapping("/test1")
    public String test1() {
       return"Hello, Swagger!";
    }

    @ApiOperation(value = "测试接口2", notes = "返回一个对象")
    @PostMapping("/test2")
    public Request1 test2(@RequestBody Request1 request1) {
       return request1;
    }

    @ApiOperation(value = "测试接口3", notes = "返回一个对象")
    @PostMapping("/test3")
    public Request2 test3(@RequestBody Request2 userRequest) {
       return userRequest;
    }

    @ApiOperation(value = "测试接口4", notes = "返回一个数字")
    @ApiParam(name = "id", value = "需要传递的ID值", defaultValue = "1", example = "1", required = true)
    @DeleteMapping("/test4/{id}")
    public Integer test4(@PathVariable("id") Integer id) {
       return id;
    }

    @ApiOperation(value = "测试接口5", notes = "返回一个名字")
    @ApiImplicitParams({
          @ApiImplicitParam(name = "id", value = "ID值", dataType = "Integer", paramType = "query"),
          @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", paramType = "query")
    })
    @PutMapping("/test5")
    public String test5(
          @RequestParam(required = false, defaultValue = "1") Integer id,
          @RequestParam(required = true, defaultValue = "oakwang") String name) {
       return id+name;
    }

    @ApiOperation(value = "测试接口6", notes = "返回一个名字")
    @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", paramType = "query")
    @GetMapping("/test6")
    public String test6(@RequestParam(required = true, defaultValue = "oakwang") String name) {
       return name;
    }

}



//=========

package org.coffeebeans.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

/**
 * <li>ClassName: MyController2 </li>
 * <li>Author: OakWang </li>
 */
@Api(tags = "模块2", description = "第二个控制器的描述")//tags 用于分组 description用于备注
@RestController
@RequestMapping("/module2")
public class MyController2 {

    @ApiOperation(value = "测试接口1", notes = "返回一个文本内容")
    @GetMapping("/test1")
    public String test1() {
       return"Hello, Swagger!";
    }

}

加上实体类：

kotlin 复制代码

package org.coffeebeans.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * <li>ClassName: Request1 </li>
 * <li>Author: OakWang </li>
 */
@Data
@ApiModel(value = "请求1", description = "请求体1")
public class Request1 {

    @ApiModelProperty(value = "用户名", example = "oakwang", required = true)
    private String username;

    @ApiModelProperty(value = "密码", example = "123456", required = true)
    private String password;

}



//=========



package org.coffeebeans.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

/**
 * <li>ClassName: Request2 </li>
 * <li>Author: OakWang </li>
 */
@Data
@ApiModel(value = "请求2", description = "请求体2")
public class Request2 {

    @Schema(description = "用户名", example = "oakwang", required = true)
    private String username;

    @Schema(description = "密码", example = "123456", required = true)
    private String password;
}

启动项目，访问成功：

禁用swagger后的效果：

测试接口：

问题处理

启动报错空指针：

1.加上配置application.properties

Spring Boot 2.6+版本对路径匹配策略进行了调整，而springfox-swagger 3.0.0在处理PathPatternParser时存在空指针问题。

ini 复制代码

# 强制使用旧版路径匹配策略
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

报错404找不到路径：

1.在SwaggerConfig类上添加@EnableSwagger2注解，以启用Swagger2的支持

2.Swagger2的默认访问路径是/swagger-ui.html，而Swagger3的默认路径是/swagger-ui/

总结

以上我们了解了Swagger的使用场景及常用注解，并且编码集成了SpringBoot2.7+Swagger3.0，当然这只是接口管理方式中的一种。

关注公众号：咖啡Beans

在这里，我们专注于软件技术的交流与成长，分享开发心得与笔记，涵盖编程、AI、资讯、面试等多个领域。无论是前沿科技的探索，还是实用技巧的总结，我们都致力于为大家呈现有价值的内容。期待与你共同进步，开启技术之旅。