526互联

三、集成Swagger

发布时间 2023-07-20 17:38:56作者: 在路上的Spike007

1. 创建新模块

 

1.1. pom.xml文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.13</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.wzh</groupId>
    <artifactId>_3_swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>_3_swagger</name>
    <description>_3_swagger</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!--springfox swagger官方Starter-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!--lombok-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

 

1.2. 创建VO类

package com.wzh._3_swagger.vo;

import lombok.Data;

@Data
public class StudentVo {
    private Integer id;
    private String name;
    private Integer age;
}

 

1.3. 创建controller类

package com.wzh._3_swagger.controller;

import com.wzh._3_swagger.vo.StudentVo;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/student")
public class StudentController {
    @GetMapping("/{id}")
    public StudentVo getById(@PathVariable("id") Integer id) {
        StudentVo student = new StudentVo();
        student.setId(id);
        student.setName("zhangsan");
        student.setAge(18);
        return student;
    }
}

 

1.4. 启动项目

若SpringBoot版本过高，报空指针异常，详见异常。

 

访问地址：http://127.0.0.1:8080/swagger-ui/index.html

 

2. Swagger2配置

2.1. Swagger2Config类

package com.wzh._3_swagger.config;

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;

/**
 * Swagger2API文档的配置
 */
@EnableSwagger2 // 启用swagger2
@Configuration
public class Swagger2Config {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo())
                // swagger 扫描包配置
                // select()获取Docket中的选择器，返回ApiSelectorBuilder构造选择器，如扫描扫描包的注解
                .select()

                /**
                 * requestHandlerSelectors：请求处理选择器
                 * basePackage()：扫描指定包下的所有接口
                 * any()：扫描所有的包
                 * none()：不扫描
                 * withClassAnnotation()：扫描指定类上的注解，参数是一个注解的放射对象
                 * withMethodAnnotation()：扫描方法上的注解
                 */
                // 指定扫描器扫描的规则（断言）
                .apis(RequestHandlerSelectors.basePackage("com.wzh._3_swagger.controller"))

                /**
                 * pathSelectors：路径选择器，过滤路径
                 * ang()：选择所有路径
                 * none()：都不选择
                 * ant()：选择指定路径
                 * regex()：正则表达式
                 */
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact(
                // 文档发布者的名称
                "wzh",
                // 文档发布者的网站地址
                "https://www.cnblogs.com/spike007blogs/",
                // 文档发布者的电子邮箱
                "wzh@163.com"
        );
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("SpringBoot集成Swagger2项目")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

 

2.2. 添加分组

	@Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("AAA组演示")
                        .description("AAA组项目描述")
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wzh._3_swagger.controller"))
                .paths(PathSelectors.any())
                .build().groupName("AAA");
    }

 

3. Swagger2注解

3.1. 接口与方法

3.1.1. @Api

@Api：是类上注解，控制整个类生成接口信息的内容

  • tags：类的名称，可以有多个值，多个值表示多个副本，在UI视图中就显示几个控制器访问菜单
  • description：描述，已过时

3.1.2. @ApiOperation

@ApiOperation：方法的说明，value值必须提供

  • value：说明方法的作用
  • notes：方法的备注说明

3.1.3. @ApiParam

@ApiParam：可以作用于方法参数和成员变量

  • name：参数别名
  • value：参数的描述
  • required：是否必须需要

3.1.4. @ApiIgnore

@Apilgnore：忽略，当前注解描述的方法或类型，不生成api文档

3.1.5. @ApiImplicitParam和@ApiImplicitParams

@ApiImplicitParam：使用在方法上，描述方法的单个参数

  • name：参数名称
  • value：描述
  • required：是否必要参数
  • paramType：参数类型
  • dataType：数据类型

 

3.2. 实体类

3.2.1. @ApiModel

@ApiModel：描述一个实体类型，这个实体类型如果成为任何一个生成api帮助文档方法的一个返回值类型的时候，此注解被解析

  • value：自定义实体
  • description：详细描述

3.2.2. @ApiModelProperty

@ApiModelProperty：实体类属性描述

  • name：字段别名
  • value：字段描述
  • required：是否是必须字段
  • example：示例数据
  • hidden：是否隐藏数据

 

3.3. 其他注解

  • @Authorization：声明要在资源或操作上使用的授权方案
  • @AuthorizationScope：描述OAuth2授权范围
  • @ResponseHeader：表示可以作为响应的一部分提供的标头
  • @ApiProperty：描述POJO对象中的属性值
  • @ApiError：接口错误所返回的信息

3.4. 添加注解的类

3.4.1. vo类

package com.wzh._3_swagger.vo;

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

@Data
@ApiModel("学生实体类-StudentVo")
public class StudentVo {
    @ApiModelProperty("主键")
    private Integer id;
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private Integer age;
}

3.4.2. controller类

package com.wzh._3_swagger.controller;

import com.wzh._3_swagger.vo.StudentVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/student")
@Api(tags = "学生信息相关控制器")
public class StudentController {
    @GetMapping("/{id}")
    @ApiOperation("通过id获取学生信息")
    public StudentVo getById(
            @ApiParam(required = true, name = "id", value = "主键") @PathVariable("id") Integer id) {
        StudentVo student = new StudentVo();
        student.setId(id);
        student.setName("zhangsan");
        student.setAge(18);
        return student;
    }

    @DeleteMapping
    @ApiOperation("通过idList删除学生信息")
    @ApiImplicitParam(name = "idList", value = "要删除的id列表", dataType = "数组")
    public void delete(
            @RequestBody List<String> idList) {
        System.out.println("idList = " + idList + "删除成功");
    }

}

 

 

异常

NullPointerException

由于SpringBoot版本为2.7（版本过高），会报如下异常

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
    at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.28.jar:5.3.28]
...
Caused by: java.lang.NullPointerException: null
	at springfox.documentation.spring.web.WebMvcPatternsRequestConditionWrapper.getPatterns(WebMvcPatternsRequestConditionWrapper.java:56) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]
	at springfox.documentation.RequestHandler.sortedPaths(RequestHandler.java:113) ~[springfox-core-3.0.0.jar:3.0.0]

 

解决方案一

添加SpringMvcConfig类

package com.wzh._3_swagger.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.DelegatingWebMvcConfiguration;

@Configuration
public class SpringMvcConfig extends DelegatingWebMvcConfiguration {
}

解决方案二

配置文件添加配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher