【Swagger】常用注解的使用、SpringBoot的整合及生产环境下屏蔽Swagger

一、引言

1、什么是Swagger？

????????Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。它使得部署管理和使用功能强大的API从未如此简单。Swagger让文件的方法、参数和模型紧密集成到服务器端的代码，允许API始终保持同步。

2、常用注解有哪些？

在软件开发中，常用注解（Annotation）主要用在Java中，并且用于对代码进行标记和说明。下面列举了一些常见的Java注解：

1. 与模型相关的注解：

   • @ApiModel：用于模型类上，对模型类做注释。
   • @ApiModelProperty：用于属性上，对属性做注释。

2. 与接口相关的注解：

   • @Api：用于controller上，对controller进行注释。
   • @ApiOperation：用于API方法上，对该API做注释，说明API的作用。
   • @ApiImplicitParams：用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明。
   • @ApiImplicitParam：用在@ApiImplicitParams注解中，也可以单独使用，说明一个请求参数的各个方面。

3. 其他常用注解：

   • @JsonProperty：用于属性上、set/get方法上，该属性序列化后可重命名。
   • @JsonFormat：用于属性或者方法上，可格式化日期属性的值。
   • @Date注解：使用这个注解可以代替实体类属性的get和set方法。
   • @Mapper注解：这个接口在编译时会生成相应的实现类。
   • @RequestMapping：指定访问方式，如果访问方式不匹配，则无法进行访问。

二、SpringBoot整合Swagger

1、导入依赖

pom.xml

        <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>

2、创建Swagger配置类

package com.wfzldr.swagger2;

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//和spring boot一起加载
@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")
//                sawgger的版本
                .version("1.0.0")
                .build();
    }

    /**
     * 创建API应用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
//                基于那个包生成文档
                .apis(RequestHandlerSelectors.basePackage("com.wfzldr.swagger2.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/");
    }

}

3、案例

@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
@RequestMapping("/book")
@Api(value = "书籍管理", tags = "书籍管理")//设置tags这个值、value的值会被覆盖
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

案例演示

    @GetMapping("/list")
    @ApiOperation(value = "查询所有的书籍")
    public JsonResponseBody<List<Book>> list() {
        ...
        return JsonResponseBody.success(list);
    }

@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 注解中；

案例演示

@GetMapping("/listAndName")
    @ApiOperation(value = "模糊查询书籍")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "书本名称", required = true, dataType = "String"),
            @ApiImplicitParam(name = "price", value = "书本价格", required = true, dataType = "Double"),
    })
    public JsonResponseBody<List<Book>> listAndName(@ApiParam(name = "name", value = "书名") String name, double price) {
       ...
        return JsonResponseBody.success(list);
    }

@ApiModel和@ApiModelProperty

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

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

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

案例演示

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

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

package com.wfzldr.swagger2.model;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;

import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;

/**
 * <p>
 * 书籍表
 * </p>
 *
 * @author wfzldr
 * @since 2023-12-19
 */
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("书籍信息")
public class Book implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 书籍id
     */
    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty("书籍编号")
    private Long id;

    /**
     * 书名
     */
    @TableField("bookname")
    @ApiModelProperty("书名")
    private String bookname;

    /**
     * 价格
     */
    @TableField("price")
    @ApiModelProperty("价格")
    private Float price;

    /**
     * 书籍类型
     */
    @TableField("booktype")
    @ApiModelProperty(value = "书籍类型")//hidden = true用来隐藏
    private String booktype;


}

@ApiParam

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

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

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

案例演示

@ApiOperation(value="新增书本信息",notes="新增书本信息")
@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<>();
}

三、生产环境下屏蔽Swagger

1、修改Swagger配置类

添加以下：

2、修改application.yml

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

????

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

3、打包

使用maven package打包测试

4、运行测试

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

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

???????