目录
一、Swagger简介
1.1 Swagger是什么？
Swagger 是一个开源的 API 设计和文档工具，它可以帮助开发人员更快、更简单地设计、构建、文档化和测试 RESTful API 。 Swagger 可以自动生成交互式 API 文档、客户端 SDK、服务器 stub 代码等，从而使开发人员更加容易地开发、测试和部署 API。
1.2 为什么要用Swagger
1.2.1:对于后端开发人员来说
- 不用再手写WiKi接口拼大量的参数，避免手写错误
- 对代码侵入性低，采用全注解的方式，开发简单
- 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
- 缺点：增加了开发成本，写接口还得再写一套参数配置
1.2.2:对于前端开发来说
- 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
- 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题
1.2.3：对于测试
- 对于某些没有前端界面UI的功能，可以用它来测试接口
- 操作简单，不用了解具体代码就可以操作
- 操作简单，不用了解具体代码就可以操作
1.3 Swagger注解
@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 | 高级特性认证时配置 |
@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 |
@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的目录。
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.ycxw.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/");
}
}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 {
@Autowired
private 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层的接口方法，点击接口可以查看该接口的一些信息，包括请求方式、地址、响应参数以及结果...
现在我也找了很多测试的朋友，做了一个分享技术的交流群，共享了很多我们收集的技术文档和视频教程。
如果你不想再体验自学时找不到资源，没人解答问题，坚持几天便放弃的感受
可以加入我们一起交流。而且还有很多在自动化，性能，安全，测试开发等等方面有一定建树的技术大牛
分享他们的经验，还会分享很多直播讲座和技术沙龙
可以免费学习！划重点！开源的！！！
qq群号：1150305204【暗号：csdn111】三、测试环境配置
在swagger配置类中我添加了一个这样的注解：
@Profile({"dev", "test"}) //dev(开发)、test(测试)、prod(生产)因为需要配置该测试文档只能在项目开发和测试阶段才能使用，在yml配置中是这样配置的：
spring:
profiles:
active: test当然这样定死显然是不好的，所以去掉这个配置，将项目直接打成jar包，通过指令设置测试环境运行。
1、设置开发环境中打开swagger测试文档
2、设置生成环境打开文档
可以看到在生成环境中不可查看接口文档
处于安全考虑，我们在发布的时候需要关闭Swagger，或者利用security授权登录才可查看接口文档
作为开发者，养成良好的文档规范习惯是非常重要的，无论使用Swagger还是其他文档工具，编写清晰、详尽的API文档都应该是我们的素养之一。
最后
感谢每一个认真阅读我文章的人，看着粉丝一路的上涨和关注，礼尚往来总是要有的，虽然不是什么很值钱的东西，如果你用得到的话可以直接拿走！
这些资料，对于做【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴我走过了最艰难的路程，希望也能帮助到你！凡事要趁早，特别是技术行业，一定要提升技术功底。
1111
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
