Swagger2之SpringBoot集成使用

前言：

? ? ? 我们对于Mybatis-Plus的分享较多，都是接触的一些数据库相关的知识，今天给大家带来的是Swagger2

Swagger2

1.介绍：

Swagger2是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：

- 接口的文档在线自动生成；
- 功能测试；

2.特点：

在线 API 文档可视化：

Swagger2 提供了一个基于 Web 的可视化界面，使得开发人员和其他团队成员能够轻松查看和理解 API 的结构和功能。这个界面允许用户直接在浏览器中测试 API，了解每个接口的请求和响应格式，并提供了交互式的方式来探索和理解 API 的功能。
功能测试：

Swagger2 不仅提供了 API 文档的生成和可视化，还可以通过界面上提供的测试功能进行功能测试。开发人员可以在 Swagger2 的界面上直接调用 API 接口，观察返回结果，确保每个接口按照预期工作。这样可以在开发阶段及时发现和修复问题。
与 Spring Boot 整合：

Swagger2 可以很容易地与 Spring Boot 集成。通过添加相应的依赖和配置，Swagger2 可以自动扫描项目中的 API，并生成相应的文档。Spring Boot 的注解与 Swagger2 的注解可以很好地配合，使得整合变得非常简单。
?

3.常用注解

注解	描述
@Api	将类标记为 Swagger 资源。
@ApiImplicitParam	表示 API 操作中的单个参数。
@ApiImplicitParams	允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel	提供有关 Swagger 模型的其他信息。
@ApiModelProperty	添加和操作模型属性的数据。
@ApiOperation	描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam	为操作参数添加额外的元数据。
@ApiResponse	描述操作的可能响应。
@ApiResponses	允许多个 ApiResponse 对象列表的包装器。
@Authorization	声明要在资源或操作上使用的授权方案。
@AuthorizationScope	描述 OAuth2 授权范围。

三、SpringBoot整合Swagger2

1. 导入pom依赖

 <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.5</version>
        </dependency>
 
        <!-- 使用1.5.22-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
 
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-models</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
            </exclusions>
        </dependency>

2. 引入配置类

（这是用于）

?Swagger2Configuration.java

介绍：

package com.lya.springbootmybatisplus.config;
 
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
//@Profile({"dev", "test"})  dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {
 
    /**
     * 创建该API的基本信息  http://项目实际地址/doc.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Swagger2")
                .description("测试系统")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("1.0.0")
                .build();
    }
 
    /**
     * 创建API应用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zking.boot.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
 
}

2.2、数据回显格式

JsonResponseBody.java

package com.lya.springbootmybatisplus.resp;

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

@Data
@ApiModel("响应对象")
public class JsonResponseBody<T> {

    @ApiModelProperty("响应码")
    private Integer code;
    @ApiModelProperty("响应信息")
    private String msg;
    @ApiModelProperty("响应数据")
    private T data;
    @ApiModelProperty("响应条数(用于分页)")
    private Long total;

    private JsonResponseBody(JsonResponseStatus jsonResponseStatus, T data) {
        this.code = jsonResponseStatus.getCode();
        this.msg = jsonResponseStatus.getMsg();
        this.data = data;
    }

    private JsonResponseBody(JsonResponseStatus jsonResponseStatus, T data, Long total) {
        this.code = jsonResponseStatus.getCode();
        this.msg = jsonResponseStatus.getMsg();
        this.data = data;
        this.total = total;
    }

    public static <T> JsonResponseBody<T> success() {
        return new JsonResponseBody<T>(JsonResponseStatus.OK, null);
    }

    public static <T> JsonResponseBody<T> success(T data) {
        return new JsonResponseBody<T>(JsonResponseStatus.OK, data);
    }

    public static <T> JsonResponseBody<T> success(T data, Long total) {
        return new JsonResponseBody<T>(JsonResponseStatus.OK, data, total);
    }

    public static <T> JsonResponseBody<T> unknown() {
        return new JsonResponseBody<T>(JsonResponseStatus.UN_KNOWN, null);
    }

    public static <T> JsonResponseBody<T> other(JsonResponseStatus jsonResponseStatus) {
        return new JsonResponseBody<T>(jsonResponseStatus, null);
    }

}

JsonResponseStatus.java

package com.lya.springbootmybatisplus.resp;

import lombok.Getter;

@Getter
public enum JsonResponseStatus {

    OK(200, "OK"),
    UN_KNOWN(500, "未知错误"),
    RESULT_EMPTY(1000, "查询结果为空！"),
    ;

    private final Integer code;
    private final String msg;

    JsonResponseStatus(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

}

3. 初步的访问swagger网址

? ? ? ? 启动项目，项目默认访问路径+/doc.html即可

4. 第三方工具引入接口?

放入这个地址：

localhost:8080/v2/api-docs

就会加载项目：

四、swagger基本使用

@Api

@Api注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
produces	返回的格式类型例如："application/json, application/xml"
consumes	接收请求参数的类型例如："application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置

案例演示

@RestController
@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
@RequestMapping("/book")
public class BookController {
 ?  ...
}

@ApiOperation

@ApiOperation注解用在方法上，说明方法的作用，每一个url资源的定义。

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
produces	返回的格式类型例如："application/json, application/xml"
consumes	接收请求参数的类型例如："application/json, application/xml"
hidden	是否在文档中显示
notes	注释说明
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
responseReference	指定对响应类型的引用。指定的引用可以是本地的，也可以是远程的*将按原样使用，并覆盖任何指定的response()类
responseHeaders	响应旁边提供的可能标题列表
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的状态码 默认 200

案例演示

@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",
 ? ? ? ? ? ?produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody<List<Book>> queryAll(){
 ? ?try {
 ? ? ? ?return bookService.queryAll();
 ?  } catch (Exception e) {
 ? ? ? ?e.printStackTrace();
 ? ? ? ?return new JsonResponseBody<>(500,e.getMessage());
 ?  }
}

@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

属性	说明
paramType	参数放在哪个地方
name	参数名称
value	参数代表的含义
dataType	参数类型
dataTypeClass	参数类型
required	是否必要
defaultValue	参数的默认值

paramType

类型	作用
path	以地址的形式提交数据，用于restful接口。请求参数采用@PathVariable获取
query	直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body	以流的形式提交，仅支持POST。请求参数采用@RequestBody获取
header	参数在request headers里边提交。请求参数采用@RequestHeader获取
form	以form表单的形式提交，仅支持POST。

案例演示

@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){
 ? ?JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);
 ? ?return json.getData();
}

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

案例演示

@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
 ? ? ? ? ?  ,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
 ? ? ? ? ? ?@ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
 ? ? ? ? ? ?@ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
 ? ? ? ? ? ?@ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,
 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? @RequestParam Double price,
 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? @RequestParam String booktype){
 ? ?return bookService.insert(Book.builder()
 ? ? ?  .bookid(UUID.randomUUID().toString().replace("-",""))
 ? ? ?  .bookname(bookname)
 ? ? ?  .booktype(booktype)
 ? ? ?  .price(price)
 ? ? ?  .build());
}

@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；

@ApiModelProperty注解描述一个model的属性。

属性	说明
value	字段说明
name	参数名称
dataType	参数类型
hidden	在文档中隐藏
required	是否必要
example	举例说明
notes	注释说明

案例演示

Controller

@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){
 ? ?return bookService.updateByPrimaryKey(book);
}

注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

Book实体类

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {
?
 ? ?/**
 ? ? * 书本编号
 ? ? */
 ? ?@ApiModelProperty(value="书本编号")
 ? ?private String bookid;
?
 ? ?/**
 ? ? * 书本名称
 ? ? */
 ? ?@ApiModelProperty(value="书本名称")
 ? ?private String bookname;
?
 ? ?/**
 ? ? * 书本价格
 ? ? */
 ? ?@ApiModelProperty(value="书本价格")
 ? ?private Double price;
?
 ? ?/**
 ? ? * 书本类型
 ? ? */
 ? ?@ApiModelProperty(value="书本类型")
 ? ?private String booktype;
?
 ? ?private static final long serialVersionUID = 1L;
}

package com.lya.springbootmybatisplus.pojo;

import com.baomidou.mybatisplus.annotation.*;

import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import jdk.internal.org.objectweb.asm.Handle;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;

/**
 * <p>
 * �鱾��?��
 * </p>
 *
 * @author lixiao
 * @since 2023-12-16
 */
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_book")
@ApiModel(value="书本对象")
public class Book implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * �鱾���
     * ASSIGN_ID雪花
     * ASSIGN_UUID 随机
     */
    @ApiModelProperty(value="书本编号")
    @TableId(value = "id", type = IdType.ASSIGN_ID)
    private Long id;

    /**
     * �鱾����
     */
    @ApiModelProperty(value="书本名称")
    @TableField("bookname")
    private String bookname;

    /**
     * �鱾�?�
     */
    @ApiModelProperty(value="书本价格")
    @TableField(value = "price",fill = FieldFill.INSERT_UPDATE)
    private Float price;

    /**
     * �鱾����
     */
    @ApiModelProperty(value="书本类型")
    @TableField(value = "booktype",fill = FieldFill.INSERT_UPDATE)
    private String booktype;

    @ApiModelProperty(hidden = true)
    @TableLogic //逻辑删除
    private Integer statu;

    @ApiModelProperty(hidden = true)
    @Version
    private Integer version;

}

@ApiParam

作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)

@ApiParam必须与@RequestParam、@PathVariable和@RequestHeader一起使用。

属性	说明
name	参数名称
value	参数简单描述
defaultValue	描述参数默认值
required	是否为必传参数, false:非必传; true:必传
allowMultiple	指定参数是否可以通过多次出现来接收多个值
hidden	隐藏参数列表中的参数
example	非请求体(body)类型的单个参数示例
examples	@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求

案例演示

@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
 ? ? ? ? ? ?@ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
 ? ? ? ? ? ?@ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
 ? ? ? ? ? ?@ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
 ? ? ?System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
 ? ?return new JsonResponseBody<>();
}

5.生产环境下屏蔽Swagger2

打jar包

运行jar

为了保证接口文档的安全，禁用了生产环境的加载，具体说明请看：

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

5.1.修改Swagger2配置类

添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2。

@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
 ? ?
 ?  ...
?
 ? ?@Override
 ? ?protected void addResourceHandlers(ResourceHandlerRegistry registry) {
 ? ? ? ?registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
 ? ? ? ?registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
 ?  }
}

5.2.修改application.yml

修改application.yml文件，配置项目系统的运行环境（dev/test/prod）

spring:
 ?#配置swagger2生产和测试环境不可用
  profiles:
 ?  active: prod

5.3.使用maven package打包测试

5.4.运行测试

打开CMD，跳转到target目录，输入命令：java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：

开发环境：dev； 生产环境：prod； 测试环境：test；

? ? ? 运行命令：?java -jar .\yxbook-0.0.1-SNAPSHOT.jar --spring.profiles.active=环境