前言:
我们对于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应用*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.zking.boot.controller")).paths(PathSelectors.any()).build();}@Overrideprotected 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)@Versionprivate 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 {... @Overrideprotected 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=环境