Swagger2接口测试文档

目录

一、Swagger简介

1.1 Swagger是什么?

1.2 为什么要用Swagger

1.3 Swagger注解

二、Spring集成Swagger

三、测试环境配置


一、Swagger简介

1.1 Swagger是什么?

        Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

1.2 为什么要用Swagger

1.2.1:对于后端开发人员来说

  • 不用再手写WiKi接口拼大量的参数,避免手写错误
  • 对代码侵入性低,采用全注解的方式,开发简单
  • 方法参数名修改、增加、减少参数都可以直接生效,不用手动维护
  • 缺点:增加了开发成本,写接口还得再写一套参数配置

1.2.2:对于前端开发来说

  • 后端只需要定义好接口,会自动生成文档,接口功能、参数一目了然
  • 联调方便,如果出问题,直接测试接口,实时检查参数和返回值,就可以快速定位是前端还是后端的问题

1.2.3:对于测试

  • 对于某些没有前端界面UI的功能,可以用它来测试接口
  • 操作简单,不用了解具体代码就可以操作
  • 操作简单,不用了解具体代码就可以操作

1.3 Swagger注解

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

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

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

属性说明
valueurl的路径值
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"
codehttp的状态码 默认 200

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

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

paramType参数:

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

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

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

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

@ApiParam注解 作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)

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

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

二、Spring集成Swagger

1、导入依赖

        <!--swager2--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!--swagger2模版样式--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version></dependency>

新版(3.0)的直接加入启动器

        <dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency>

 3.0版本后不需要在加入@enableopenapi,和@enableswagger2这两个注解

2、创建Swagger2配置类

package com.ycxw.boot.config;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("ycxw320.blog.csdn.net").version("1.0.0").build();}/*** 创建API应用* apis接口包扫描路径* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,* 本例采用指定扫描的包路径来定义指定要建立API的目录。*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.ycxw.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/");}}

3、接着通过mybatis生成代码...

4、Swagger类与属性注释

package com.ycxw.boot.entity;import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;import java.io.Serializable;/*** <p>* 书本信息表* </p>** @author 云村小威* @since 2023-12-20*/
@Data
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("书籍对象")
public class Book implements Serializable {private static final long serialVersionUID = 1L;/*** 书本编号*/@TableId("id")@ApiModelProperty("书籍编号")private String id;/*** 书本名称*/@TableField("bookname")@ApiModelProperty("书籍名称")private String bookname;/*** 书本价格*/@TableField("price")@ApiModelProperty("书籍价格")private Float price;/*** 书本类型*/@TableField("booktype")@ApiModelProperty("书籍类型")private String booktype;/*逻辑删除(隐藏)*/@TableField("status")@ApiModelProperty(hidden = true)private Integer status;/*乐观锁(隐藏)*/@TableField("version")@ApiModelProperty(hidden = true)private Integer version;}

5、Controller与接口方法注释

package com.ycxw.boot.controller;import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.toolkit.StringUtils;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.ycxw.boot.entity.Book;
import com.ycxw.boot.service.IBookService;
import com.ycxw.boot.tools.JsonResponseBody;
import com.ycxw.boot.tools.JsonResponseStatus;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.List;
import java.util.Objects;/*** <p>* 书本信息表 前端控制器* </p>** @author 云村小威* @since 2023-12-20*/
@RestController
@RequestMapping("/book")
@Api(value = "书籍管理")
public class BookController {@Autowiredprivate IBookService bookService;@GetMapping("/list")@ApiOperation(value = "书籍查询所有")public JsonResponseBody<List<Book>> list() {List<Book> list = bookService.list();if (!list.isEmpty()) {return JsonResponseBody.other(JsonResponseStatus.OK);} else {return JsonResponseBody.other(JsonResponseStatus.RESULT_EMPTY);}}@PostMapping("/save")@ApiOperation(value = "新增书籍")public JsonResponseBody<Boolean> save(Book book) {boolean save = bookService.save(book);return JsonResponseBody.success(save);}@GetMapping("/likeName")@ApiOperation(value = "获取商品集合,模糊查询")public JsonResponseBody<List<Book>> list(Book goods) {QueryWrapper<Book> wrapper = new QueryWrapper<>();wrapper.like(StringUtils.isNotEmpty(goods.getBookname()), "bookname", goods.getBookname());List<Book> list = bookService.list(wrapper);return JsonResponseBody.success(list);}@GetMapping("/show")@ApiOperation(value = "获取商品集合,模糊查询+大于查询")@ApiImplicitParams({@ApiImplicitParam(name = "price", paramType = "query", value = "价格", required = true),@ApiImplicitParam(name = "bookname", paramType = "query", value = "名称", required = true)})public JsonResponseBody<List<Book>> listByNameAndPrice(Double price, String bookname) {QueryWrapper<Book> wrapper = new QueryWrapper<>();wrapper.like(StringUtils.isNotEmpty(bookname), "bookname", bookname);wrapper.gt(Objects.nonNull(price), "price", price);List<Book> list = bookService.list(wrapper);return JsonResponseBody.success(list);}@GetMapping("/page")@ApiOperation(value = "获取商品集合,分页查询+模糊查询")public JsonResponseBody<List<Book>> listPage(@ApiParam(name = "bookname", value = "模糊查询关键字")@RequestParam("bookname")String bookname) {QueryWrapper<Book> wrapper = new QueryWrapper<>();wrapper.like(StringUtils.isNotEmpty(bookname), "bookname", bookname);Page<Book> page = new Page<>();Page<Book> res = bookService.page(page, wrapper);return JsonResponseBody.success(res.getRecords(), res.getTotal());}}

6、访问本地链接

启动项目访问:http://localhost:8080/doc.html

        通过Swagger视图可以看到该项目的一些信息,还有每个controller层的接口方法,点击接口可以查看该接口的一些信息,包括请求方式、地址、响应参数以及结果...

三、测试环境配置

在swagger配置类中我添加了一个这样的注解:

@Profile({"dev", "test"})  //dev(开发)、test(测试)、prod(生产)

 因为需要配置该测试文档只能在项目开发和测试阶段才能使用,在yml配置中是这样配置的:

spring:profiles:active: test

当然这样定死显然是不好的,所以去掉这个配置,将项目直接打成jar包,通过指令设置测试环境运行。

1、设置开发环境中打开swagger测试文档

2、设置生成环境打开文档

可以看到在生成环境中不可查看接口文档 

        处于安全考虑,我们在发布的时候需要关闭Swagger,或者利用security授权登录才可查看接口文档

        作为开发者,养成良好的文档规范习惯是非常重要的,无论使用Swagger还是其他文档工具,编写清晰、详尽的API文档都应该是我们的素养之一。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/235744.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Linux之进程(五)(进程控制)

目录 一、进程创建 1、fork函数创建进程 2、fork函数的返回值 3、fork常规用法 4、fork调用失败的原因 二、进程终止 1、进程终止的方式 2、进程退出码 3、进程的退出方法 三、进程等待 1、进程等待的必要性 2、wait函数 3、waitpid函数 四、进程程序替换 1、概念…

Android studio中导入opencv库

具体opencv库的导入流程参考链接&#xff1a;Android Studio开发之路 &#xff08;五&#xff09;导入OpenCV以及报错解决 一、出现的错误&#xff1a;NullPointerException: Cannot invoke “java.io.File.toPath()” because “this.mySdkLocation” is null 解决办法&#…

java获取当前线程的上下文类加载器(context ClassLoader)

当前线程的上下文类加载器初始设置等于加载该应用的类加载器。 代码示例&#xff1a; package com.thb;public class Demo4 {public static void main(String[] args) {System.out.println(Thread.currentThread().getContextClassLoader());} }运行输出&#xff1a;

地质灾害监测预警解决方案

目录 1.前言 2.滑坡监测站建设方案 2.1建站方案 2.2监测指标体系 2.3监测设备配置 3.地面沉降监测建设方案 3.1建设方案 3.2监测指标体系 3.3监测设备配置 4.泥石流监测站建设方案 4.1建设方案 4.2监测指标体系 4.3监测设备配置 5.岩溶塌陷监测站方案 5.1建站方案…

深入理解网络 I/O:FileOutputStream、BufferFileOutputStream、ByteBuffer

&#x1f52d; 嗨&#xff0c;您好 &#x1f44b; 我是 vnjohn&#xff0c;在互联网企业担任 Java 开发&#xff0c;CSDN 优质创作者 &#x1f4d6; 推荐专栏&#xff1a;Spring、MySQL、Nacos、Java&#xff0c;后续其他专栏会持续优化更新迭代 &#x1f332;文章所在专栏&…

java8实战 lambda表达式、函数式接口、方法引用双冒号(中)

前言 书接上文&#xff0c;上一篇博客讲到了lambda表达式的应用场景&#xff0c;本篇接着将java8实战第三章的总结。建议读者先看第一篇博客 其他函数式接口例子 上一篇有讲到Java API也有其他的函数式接口&#xff0c;书里也举了2个例子&#xff0c;一个是java.util.functi…

java并发-ConcurrentHashMap 在Java7 和 8 的区别

文章目录 1.Java 7 版本的 ConcurrentHashMap2.Java 8 版本的 ConcurrentHashMap3.分析 Java 8 版本的 ConcurrentHashMap 的重要源码3.1.Node 节点3.2.put 方法源码分析3.3.get 方法源码分析 4.对比 Java7 和 Java8 的异同和优缺点4.1.并发度4.2.保证并发安全的原理4.3.遇到 H…

Jmeter实现CSV数据批量导入

CSV&#xff1a;逗号分隔值&#xff0c;是一种简洁且常见的数据存储格式。 1、参数化&#xff1a; 在Jmeter中&#xff0c;可以通过“用户自定义的变量”来实现参数化使操作方便&#xff0c;使用语法位&#xff1a;${参数名}&#xff0c;如下图&#xff1a; 而CSV也同理&…

本地文件内容搜索神器AnyTXT Searcher如何搭建与远程访问

文章目录 前言1. AnyTXT Searcher1.1 下载安装AnyTXT Searcher 2. 下载安装注册cpolar3. AnyTXT Searcher设置和操作3.1 AnyTXT结合cpolar—公网访问搜索神器3.2 公网访问测试 4. 固定连接公网地址 前言 你是否遇到过这种情况&#xff0c;异地办公或者不在公司&#xff0c;想找…

java注意项--更新中

前言&#xff1a; 1.大小写规定 1.1.类名和接口名&#xff1a;每个单词首字母大写。如GoodStudent&#xff1b; 是一个单词的时候首字母大写。如Student&#xff1b; 1.2.变量和方法名&#xff1a;第一个首字母小写&#xff0c;后序首字母大写。如firstName&#xff1b; 是一…

vue的语法模板与数据绑定的说明

vue的两大模板语法&#xff1a; 1.插值语法 2.指定语法 插值语法&#xff1a;{{}} 功能&#xff1a;用于解析标签体的内容 写法&#xff1a;{{xxx}},xxx是js表达式,且可以直接读取到data中的所有属性 指定语法&#xff1a; 功能:用于解析标签(包括:标签属性、标…

ChatGPT助力Excel数据分析:让你的工作事半功倍!

文章目录 一、ChatGPT简介二、ChatGPT在Excel数据分析中的应用1. 数据清洗2. 数据处理3. 数据分析4. 数据可视化 三、如何使用ChatGPT进行Excel数据分析1. 安装ChatGPT插件2. 输入问题或命令3. 查看结果并调整参数4. 导出结果并分享四、总结与展望 《巧用ChatGPT高效搞定Excel数…

苹果cms论坛多播放源自动采集 /采集在线影视网站/苹果CMS影视站采集器

源码介绍&#xff1a; 苹果cms论坛多播放源自动采集、采集在线影视网站&#xff0c;作为苹果CMS影视站采集器&#xff0c;它能轻松获取在线影视网站资源。 苹果 cms 论坛这是一个基于Vue和Gin实现的在线观影网站。项目采用 vite vue 作为前端技术栈, 使用 ElementPlus 作为 …

el-select 全选

<template><div class"container"><el-selectv-model"choosedList"clearablemultiplecollapse-tagsplaceholder"请选择"change"select_Change"><div style"padding: 0 20px; line-height: 34px">&l…

JVM快速入门

JVM 字节码 字节码文件的组成 字节码由五个部分组成&#xff1a;基础信息 常量池 字段 方法 属性 基础信息&#xff1a; 魔数、字节码文件对应的版本号、访问标识&#xff08;public final&#xff09;、该类的父类索引、该类实现哪些接口的索引 魔数&#xff1a;文件无法…

顶级加密混淆混淆工具测评:ipagurd

摘要 JavaScript代码安全需求日益增长&#xff0c;因此JavaScript混淆工具的使用变得广泛。本文将对专业、商业JavaScript混淆工具ipagurd进行全面评估&#xff0c;通过比较其功能、操作便捷性、免费试用、混淆效果等方面&#xff0c;帮助开发者选择适合自己项目需求的工具。 …

期货平仓日历(期货平仓日期汇总)

什么是期货平仓日历&#xff1f; 期货是一种高风险高收益的投资品种。而期货交易不同于股票等其他投资品种的交易&#xff0c;期货交易需要在一定时间内才能买卖。而期货平仓日历就是指期货交易中规定的所有合约的平仓日期汇总。 常见期货平仓日期和时间&#xff1f; 不同的…

关于EasyExcel 合并单元格方法该如何实现

在做一个业务的导出&#xff0c;目前遇到一个需求&#xff0c;如下图&#xff1a; import com.alibaba.excel.metadata.CellData; import com.alibaba.excel.metadata.Head; import com.alibaba.excel.write.handler.CellWriteHandler; import com.alibaba.excel.write.metad…

在mt5上哪里可以添加指数品种?

在MT5交易平台上&#xff0c;您可以通过以下步骤添加指数品种&#xff08;如股票指数、商品指数等&#xff09;到您的市场观察窗口中&#xff1a; Exness手机登录平台学习指南 步骤一&#xff1a;打开市场观察窗口&#xff1a; 打开MT5交易平台。 在左侧的“市场观察”窗口中&…

高集成高能效FAN21SV04MPX 单输入集成同步降压调节器技术解析

FAN21SV04MPX 是一款高效、小型、可编程频率的 4 A 集成同步降压调节器。FAN21SV04MPX 采用经过优化的互联方式将同步MOSFET和控制器/驱动器包含在一个封装中&#xff0c;使得设计人员能够使用最少的外部元件&#xff0c;在较小面积中满足高电流要求&#xff0c;从而降低成本。…