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的目录。
     */
    @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层的接口方法，点击接口可以查看该接口的一些信息，包括请求方式、地址、响应参数以及结果...

三、测试环境配置

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

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

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

spring:
  profiles:
    active: test

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

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

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

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

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

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

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

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

Qt 国际化——创建中英文翻译步骤

Qt 国际化——创建中英文翻译步骤

Qt 国际化——创建中英文翻译步骤 说明&#xff1a;之前我的csdn博客&#xff0c;第一篇文章发表的就是Qt国际化的文章&#xff08;点击打开&#xff09;&#xff0c;写的也过于简单了&#xff1a; 今天&#xff0c;这篇文章再详细的记录下&#xff0c;中英文翻译的步骤。 一…
阅读更多...
【Python】循环语句

【Python】循环语句

一、while循环的基础语法 二、while循环的嵌套应用 三、while循环的嵌套案例 四、for循环的基础语法 五、for循环的嵌套应用 六、循环中断 : break和continue 一、while循环的基础语法 使用while循环的基础应用 while循环语句 while循环注意点 while的条件需得到布尔类型&am…
阅读更多...
高通平台开发系列讲解（系统篇）系统关机流程

高通平台开发系列讲解（系统篇）系统关机流程

文章目录 一、关机流程图二、执行关机流程2.1、kernel_shutdown_prepare流程2.2、migrate_to_reboot_cpu流程2.3、syscore_shutdown流程2.4、machine_power_off流程沉淀、分享、成长，让自己和他人都能有所收获！😄 📢本篇章主要图解高通平台系统关机流程。 一、关机流程图…
阅读更多...
Go后端开发 -- 环境搭建

Go后端开发 -- 环境搭建

Go后端开发 – 环境搭建 文章目录 Go后端开发 -- 环境搭建一、环境配置二、IDE的选择三、使用go mod构建项目1.初始化项目2.添加依赖项3.运行项目 四、环境报错1.VS Code中gopls报错 一、环境配置 Go官网下载地址&#xff1a;https://golang.org/dl/ https://go.dev/dl/ Go官方…
阅读更多...
SpringSecurity深度解析与实践（1）

SpringSecurity深度解析与实践（1）

目录 引言1. SpringSecurity1.1 SpringSecurity简介1.2 SpringSecurity工作原理1.3.特点 2. SpringSecurity的快速使用总结 引言 SpringSecurity作为Spring框架中的一个重要组成部分&#xff0c;扮演着保护应用程序安全的重要角色。本文将深入探讨SpringSecurity的原理、使用方…
阅读更多...
C# .Net学习笔记—— Expression 表达式目录树

C# .Net学习笔记—— Expression 表达式目录树

一、什么是表达式目录树 &#xff08;1&#xff09;Expression我们称为是表达式树&#xff0c;是一种数据结构体&#xff0c;用于存储需要计算&#xff0c;运算的一种结构&#xff0c;这种结构可以只是存储&#xff0c;而不进行运算。通常表达式目录树是配合Lambda一起来使用的…
阅读更多...
PySpark中DataFrame的join操作

PySpark中DataFrame的join操作

内容导航 类别内容导航机器学习机器学习算法应用场景与评价指标机器学习算法—分类机器学习算法—回归机器学习算法—聚类机器学习算法—异常检测机器学习算法—时间序列数据可视化数据可视化—折线图数据可视化—箱线图数据可视化—柱状图数据可视化—饼图、环形图、雷达图统…
阅读更多...
常见可视化大屏编辑器有哪些？

常见可视化大屏编辑器有哪些？

前言&#xff1a; 在当今数字化时代&#xff0c;可视化大屏编辑器成为了数据展示和决策支持的重要工具。大屏编辑器不仅仅是数据的呈现&#xff0c;更是数据背后的故事的讲述者。它通过图表、图形和实时数据的呈现&#xff0c;为用户提供了全面的信息视图&#xff0c;帮助用户更…
阅读更多...
【无人机学习篇】构建mavros机载电脑连接，从机载电脑获取pixhawk数据

【无人机学习篇】构建mavros机载电脑连接，从机载电脑获取pixhawk数据

&#xff08;本文基于的pixhawk版本&#xff1a;6X minibase V2.2 &#xff0c;固件&#xff1a;apm&#xff09; 整个的步骤&#xff08;baseline&#xff09;&#xff1a; 具体的每一步都可以在网上查到教程&#xff0c;这里只是梳理出一个流程。并且ubantu与ros的版本也不是…
阅读更多...
Python - 深夜数据结构与算法之 Map Set

Python - 深夜数据结构与算法之 Map Set

目录 一.引言 二.Map 与 Set 1.Hash Table 2.Hash Function 3.Hash Collisions 4.Java/Python Code 三.经典算法实战 1.Two-Sum [1] 2.Group-Anagrams [49] 3.Valid-Anagram [242] 四.总结 一.引言 前面介绍了列表 List 及其衍生的栈 Stack 与队列 Queue&#xff0…
阅读更多...
VR全景技术在政务服务中有哪些应用，为政务服务带来什么便利

VR全景技术在政务服务中有哪些应用，为政务服务带来什么便利

引言&#xff1a; 随着科技的不断发展&#xff0c;虚拟现实&#xff08;VR&#xff09;全景技术正逐渐成为政务服务领域的一项重要工具。其独特的沉浸式体验为政务服务带来了全新的便利&#xff0c;提升了公众参与的积极性。 一、VR全景技术在政务服务中的应用 1.虚拟实景政务…
阅读更多...
多表插入、删除操作（批量）——后端

多表插入、删除操作（批量）——后端

多表插入 场景&#xff1a;当添加一个菜品时&#xff0c;还需要记录菜品的口味信息&#xff0c;因此需要对菜品表&#xff08;dish&#xff09;和口味表&#xff08;dish_flavor&#xff09;同时进行插入操作。 两个表的字段&#xff1a; 代码思路&#xff1a;由DishControll…
阅读更多...
市场全局复盘 20231220

市场全局复盘 20231220

短线核心&#xff1a;不参与任何级别的调整 昨日回顾&#xff1a; SELECT CODE,成交额排名,净流入排名,代码,名称,DDE大单金额,涨幅,主力净额,DDE大单净量,CONVERT(DATETIME, 最后封板, 120) AS 最后封板,涨停分析,_3日涨幅百分比,连板天,封单额,封单额排名,DDE散户数量,总金额…
阅读更多...
Android Studio使用Genymotion

Android Studio使用Genymotion

1. Genymotion介绍 GenyMotion速度之快令人发指&#xff0c;模拟效果堪比真机调试&#xff0c;支持绝大部分的模拟器功能&#xff0c;甚至包括语音&#xff0c;Google Now&#xff0c;支持eclipse, android studio。非常适合用来开发和演示效果。 2. Genymotion下载 Genymotio…
阅读更多...
CentOS操作学习（二）

CentOS操作学习（二）

上一篇学习了CentOS的常用指令CentOS指令学习-CSDN博客 现在我们接着学习 一、Vi编辑器 这是CentOS中自带的编辑器 三种模式 进入编辑模式后 i&#xff1a;在光标所在字符前开始插入a&#xff1a;在光标所在字符串后开始插入o&#xff1a;在光标所在行的下面另起一新行插入…
阅读更多...
Java操作Word修订功能：启用、接受、拒绝、获取修订

Java操作Word修订功能：启用、接受、拒绝、获取修订

Word的修订功能是一种在文档中进行编辑和审阅的功能。它允许多个用户对同一文档进行修改并跟踪这些修改&#xff0c;以便进行审查和接受或拒绝修改。修订功能通常用于团队合作、专业编辑和文件审查等场景。 本文将从以下几个方面介绍如何使用免费工具Free Spire.Doc for Java在…
阅读更多...
使用包、Crate 和模块管理项目（下）

使用包、Crate 和模块管理项目（下）

1、使用 use 关键字将路径引入作用域 在之前的示例中我们引用模块中的函数或者结构体之类的&#xff0c;都是需要用到相对路径或者绝对路径去引用&#xff0c;然尔在这里&#xff0c;有一种方法可以简化这个过程。我们可以使用 use 关键字创建一个短路径&#xff0c;然后就可以…
阅读更多...
创建Maven Web工程

创建Maven Web工程

目录下也会有对应的生命周期。其中常用的是&#xff1a;clean、compile、package、install。 比如这里install &#xff0c;如果其他项目需要将这里的模块作为依赖使用&#xff0c;那就可以 install 。安装到本地仓库的位置&#xff1a; Java的Web工程&#xff0c;所以我们要选…
阅读更多...
Ubuntu上安装MySQL以及hive

Ubuntu上安装MySQL以及hive

Ubuntu上安装MySQL以及hive 一、安装MySQL1、更新软件源2、安装 MySQL3、启动 MySQL&#xff0c;并登录 MySQL4、关闭 MySQL 指令&#xff1a;5、修改登录密码6、关闭 mysql&#xff0c;然后重新进入 二、安装hive1、创建 hive 的数据库2、下载压缩包3、修改环境配置文件并激活…
阅读更多...
【ECharts】折线图

【ECharts】折线图

文章目录 折线图1折线图2折线图3示例 参考&#xff1a; Echarts官网 Echarts 配置项 折线图1 带X轴、Y轴标记线&#xff0c;其中X轴是’category’ 类目轴&#xff0c;适用于离散的类目数据。 let myChart echarts.init(this.$refs.line_chart2); let yList [400, 500, 6…
阅读更多...
最新文章

Copyright @ 2022~2023