位置：首页-资讯-后端开发

SpringBoot整合Swagger2的完整过程记录

2024-04-02 19:55

短信预约 -IT技能 免费直播动态提醒

前言

springBoot作为微服务首选框架，为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。

swagger可以通过代码和注释自动为web项目生成在线文档，这里使用swagger。

当 SpringBoot 代码中 SpringMVC 使用自动化配置类 WebMvcAutoConfiguration 时，其整合 Swagger2 的方法如下。

如果 SpringMVC 的配置过程使用了 WebMvcConfigurationSupport；则如下的整合方法不适合。

一、Spring Boot Web 整合 Swagger2 过程

Spring Boot Web 项目整合 Swagger2 主要有两个过程：

添加 Swagger2 相关依赖。
配置 Swagger2 配置类。

1.1、添加 Swagger2 相关依赖

首先要对 Spring Boot Web 的项目，添加 Swagger2 相关的依赖：


<dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>

1.2、配置 Swagger2 配置类


@Configuration
@EnableSwagger2
public class Swagger {
   //创建 Docket 的Bean
   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         //select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现
         .select()
         //要扫描的包
         .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
  //选择API路径
         .paths(PathSelectors.any())
         .build();
   }
  //创建文档的基本信息
   public ApiInfo apiInfo(){
       return new ApiInfoBuilder()
         .title("Swagger UI 的标题")
         .description("用restful风格写接口")
         .termsOfServiceUrl("")
         .version("1.0")
         .build();
   }
}

二、配置 Swagger2 接口常用注解

2.1、@Api 请求类说明

写在controller类定义上方,用于说明类的作用。


@Api(value = "Swagger Test Control", 
     description = "演示Swagger用法的Control类", 
     tags = "Swagger Test Control Tag")

2.2、@ApiOperation 方法的说明

写在REST接口上方，用于说明方法的作用。


@ApiOperation(
value="创建用户", 
notes="根据User对象创建用户")

2.3、@ApiImplicitParams 和 @ApiImplicitParam 方法参数说明


@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值
--------------------------------------------------------------------
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "ID", dataType = "Long"),
    @ApiImplicitParam(name = "user", value = "用户", dataType = "User")
})

2.4、@ApiResponses 和 @ApiResponse 方法返回值的说明


@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
-------------------------------------------------------------------
@ApiResponses({
    @ApiResponse(code = 400, message = "权限不足"),
    @ApiResponse(code = 500, message = "服务器内部异常") }
)

2.5、@ApiModel 和 @ApiModelProperty

@ApiModel 用于JavaBean 上面，表示一个JavaBean。这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候。

@ApiModelProperty 用对象接收参数时，描述对象的一个字段。


@ApiModel( description = "学生")
public class Student {
    @ApiModelProperty(value = "主键id")
    private String id;
    @ApiModelProperty(value = "名称", required = true)
    private String name;
    @ApiModelProperty(value = "年龄", required = true)
    private int age;
}