Swagger使用详解

目录

一、简介

二、SwaggerTest项目搭建

1. pom.xml

2. entity类

3. controller层

三、基本使用

1. 导入相关依赖

2. 编写配置文件

2.1 配置基本信息

2.2 配置接口信息

2.3 配置分组信息

2.3.1 分组名修改

2.3.2 设置多个分组

四、常用注解使用

1. @ApiModel

2.@ApiModelProperty

3.@ApiOperation

4. @ApiParam

五、Swagger接口调用

六、添加请求头


一、简介

前言

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步

Why Swagger?

当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成,在这种开发模式下,维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的,这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本。而 swagger 给我们提供了一个全新的维护 API 文档的方式

作为后端开放人员,最烦的事就是自己写接口文档和别人没有写接口文档,不管是前端还是后端开发,多多少少都会被接口文档所折磨,前端会抱怨后端没有及时更新接口文档,而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题,以一套标准的规范定义接口以及相关的信息,就能做到生成各种格式的接口文档,生成多种语言和客户端和服务端的代码,以及在线接口调试页面等等。只需要更新 Swagger 描述文件,就能自动生成接口文档,做到前端、后端联调接口文档的及时性和便利性

作用
1.支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便

2.提供 Web 页面在线测试 API:Swagger 生成的文档支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口

二、SwaggerTest项目搭建

1. pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.swagger</groupId><artifactId>SwaggerTest</artifactId><version>1.0-SNAPSHOT</version><properties><maven.compiler.source>8</maven.compiler.source><maven.compiler.target>8</maven.compiler.target></properties><dependencies><!--        springboot 启动依赖--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId><version>2.2.6.RELEASE</version></dependency><!--     springboot web 依赖--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><version>2.2.6.RELEASE</version></dependency><!--lombok依赖--><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.24</version></dependency><!-- swagger --><dependency><groupId>io.springfox</groupId><artifactId>springfox-spring-web</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency></dependencies></project>

2. entity类

package com.swagger.entity;import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {private Long id;private String name;private int age;
}

3. controller层

package com.swagger.controller;import com.swagger.entity.User;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/user")
public class UserController {@GetMapping("/getByName")public String getByName(){return "访问getByName成功";}@PostMapping("/login")public String login(@RequestBody User user){return "登录成功";}
}

三、基本使用

1. 导入相关依赖

        <!-- swagger --><dependency><groupId>io.springfox</groupId><artifactId>springfox-spring-web</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

2. 编写配置文件

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}

这个时候 Swagger 已经算是整合到项目之中了,可以启动下服务,输入:http://localhost:8080/swagger-ui.html# 即可查看Swagger文档,可以看到如下信息

  • 基本信息
  • 接口信息
  • 实体类信息

2.1 配置基本信息

Swagger 在自己的实例Docket中可以设置自定义基本信息于ApiInfo对象中,下图为Swagger默认的基本信息

ApiInfo中默认的基本信息

  • title:Api Documentation
  • description:Api Documentation
  • version:1.0
  • termsOfServiceUrl:urn:tos
  • contact:无
  • license:Apache 2.0
  • licenseUrl:http://www.apache.org/licenses/LICENSE-2.0

这些信息都不是我们需求的,我们可以在Swagger配置文件中去配置属于我们自己项目的接口文档信息,代码如下

package com.swagger.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {@Beanpublic Docket docket() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)// 配置基本信息.apiInfo(apiInfo());}// 基本信息设置private ApiInfo apiInfo() {Contact contact = new Contact("Keke", // 作者姓名"https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址"1781125992@qq.com"); // 作者邮箱return new ApiInfoBuilder().title("SwaggerTest-接口文档") // 标题.description("这是关于Swagger学习测试的接口文档") // 描述.termsOfServiceUrl("https://www.baidu.com") // 跳转连接.version("1.0") // 版本.license("Swagger-的使用(详细教程)").licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501").contact(contact).build();}}

重新启动服务,效果如下

2.2 配置接口信息

默认情况下,Swagger是会展示所有的接口信息的,包括最基础的basic-error相关接口

有时候我们希望不要展示 basic-error-controller 相关的接口,或者有其他需求,可以看以下代码和注释理解运用

@Beanpublic Docket docket() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)//配置基本信息.apiInfo(apiInfo())// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors//.any() // 扫描全部的接口,默认//.none() // 全部不扫描.basePackage("com.swagger.controller") // 扫描指定包下的接口,最为常用//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口).paths(PathSelectors.any() // 满足条件的路径,该断言总为true//.none() // 不满足条件的路径,该断言总为false(可用于生成环境屏蔽 swagger)//.ant("/user/**") // 满足字符串表达式路径//.regex("") // 符合正则的路径).build();}

可以看到,basic-error相关接口我们已经去除了

2.3 配置分组信息

Swagger默认只有一个分组,名为default,如果不设置,所有的接口都会在这个分组下。在多模块项目下,我们通常会需要建立多个分组来分类管理这些接口,来防止接口混杂在一起

2.3.1 分组名修改
 @Beanpublic Docket docket() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)//设置分组名.groupName("admin")}

可以看到分组名修改为admin

2.3.2 设置多个分组

实际上创建几个Docket对象,就有几个分组,代码如下

package com.swagger.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {@Beanpublic Docket docket() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)//设置分组名.groupName("admin")//配置基本信息.apiInfo(apiInfo())// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors//.any() // 扫描全部的接口,默认//.none() // 全部不扫描.basePackage("com.swagger.controller") // 扫描指定包下的接口,最为常用//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口).paths(PathSelectors.any() // 满足条件的路径,该断言总为true//.none() // 不满足条件的路径,该断言总为false(可用于生成环境屏蔽 swagger)//.ant("/user/**") // 满足字符串表达式路径//.regex("") // 符合正则的路径).build();}@Beanpublic Docket docket1() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)//设置分组名.groupName("blog")//配置基本信息.apiInfo(apiInfo())// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors//.any() // 扫描全部的接口,默认//.none() // 全部不扫描.basePackage("com.swagger.controller") // 扫描指定包下的接口,最为常用//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口).paths(PathSelectors.any() // 满足条件的路径,该断言总为true//.none() // 不满足条件的路径,该断言总为false(可用于生成环境屏蔽 swagger)//.ant("/user/**") // 满足字符串表达式路径//.regex("") // 符合正则的路径).build();}// 基本信息设置private ApiInfo apiInfo() {Contact contact = new Contact("Keke", // 作者姓名"https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址"1781125992@qq.com"); // 作者邮箱return new ApiInfoBuilder().title("SwaggerTest-接口文档") // 标题.description("这是关于Swagger学习测试的接口文档") // 描述.termsOfServiceUrl("https://www.baidu.com") // 跳转连接.version("1.0") // 版本.license("Swagger-的使用(详细教程)").licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501").contact(contact).build();}}

可以看到blog模块分组的接口文档也在UI界面中展示出来

四、常用注解使用

1. @ApiModel

该注解是作用在类上的,用来描述类的一些基本信息的

相关属性:

  • value:提供类的一个备用名,如果不设置,默认情况下将使用 class 类的名称
  • description:对于类,提供一个详细的描述信息
  • parent:这个属性用于描述的是类的一些父类信息
  • discriminator:这个属性解释起来比较麻烦,因为这个类主要体现在断言当中
  • subTypes:可以通过这个属性,指定我们想要使用的子类

2.@ApiModelProperty

添加和操作属性模块的数据

package com.swagger.entity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "user实体类")
public class User {@ApiModelProperty(value = "id主键")private Long id;@ApiModelProperty(value = "用户姓名")private String name;@ApiModelProperty(value = "用户年龄")private int age;
}

可以看到Model展示出来一些描述信息

3.@ApiOperation

该注解用来对某个方法/接口进行描述

 @GetMapping("/getByName")@ApiOperation(value = "根据姓名查询用户")public String getByName(){return "访问getByName成功";}

可以看到接口文档这里多了 根据姓名查询用户 的描述

4. @ApiParam

该注解使用在方法上或者参数上,字段说明,表示对参数的添加元数据(说明或者是否必填等)

相关属性:

  • name:参数名
  • value:参数说明
  • required:是否必填
 @GetMapping("/getByName/{id}")@ApiOperation(value = "根据id查询用户")public String getById(@ApiParam(value = "用户id",required = true) @PathVariable Long id){return "访问getById成功";}

可以看到,添加@ApiParam注解后,接口文档多了对参数的相应描述说明

五、Swagger接口调用

swagger 除了让前后端交互变得方便,在swagger中也可以发起请求测试接口,只需要填写好请求所需要的参数信息即可

点击Excute就可以看到接口响应的结果了

六、添加请求头

在登录注册类似涉及安全验证的业务,例如SpringSecurity框架中我们的接口是需要获取请求头信息的,这样的话就还需要在 swagger 配置中添加请求头的配置。

    @Beanpublic Docket docket() {// 设置请求头List<Parameter> parameters = new ArrayList<>();parameters.add(new ParameterBuilder().name("token") // 字段名.description("token") // 描述.modelRef(new ModelRef("string")) // 数据类型.parameterType("header") // 参数类型.defaultValue("default value") // 默认值:可自己设置.hidden(true) // 是否隐藏.required(false) // 是否必须.build());// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2).groupName("mike") // 修改组名为 "mike"// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口,最为常用).paths(PathSelectors.any() // 满足条件的路径,该断言总为true).build()// 添加请求头参数.globalOperationParameters(parameters);}

接口

    @GetMapping(value = "/getToken")@ApiOperation(value = "获取请求头中的token信息")public void getToken(@RequestHeader(value = "token",required = true) String token) {// 直接获取 token 信息System.out.println("token = " + token);// 通过代码获取ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();if (servletRequestAttributes != null) {HttpServletRequest request = servletRequestAttributes.getRequest();String header = request.getHeader("token");System.err.println("header = " + header);}}

这样重启服务,接口就可以设置请求头了

执行后,后端控制台可以打印http请求带来的token的信息

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

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

相关文章

BS EN 12104-2023 软木地砖检测

软木地砖是指含有烧结成分的软木制成的块状砖&#xff0c;可用于地面覆盖物&#xff0c;装饰层等&#xff0c;具有脚感柔软舒适&#xff0c;防滑性能好&#xff0c;静音等性能&#xff0c;同时也其耐磨性较差&#xff0c;不易清洁。 BS EN 12104-2023软木地砖测试 测试项目 测…

Linux 指令心法(七)`cat` 查看、合并和创建文本文件

文章目录 命令的概述和用途命令的用法命令行选项和参数的详细说明命令的示例命令的注意事项或提示 命令的概述和用途 cat 是 “concatenate” 的缩写&#xff0c;它是一个 Linux 和 Unix 系统中的命令&#xff0c;用于查看、合并和创建文本文件。cat 主要用于以下几个方面&…

MongoDB-索引Index

索引Index 索引-Indexa) 概述b) 索引的类型b.1) 单字段索引b.2) 复合索引b.3) 其他索引 c) 索引的管理操作c.1) 索引的查看c.2) 索引的创建c.3) 索引的移除 d) 索引的使用d.1) 执行计划d.2) 涵盖的查询 索引-Index a) 概述 索引支持在MongoDB中高效地执行查询。如果没有索引&…

IDEA的使用(三)Debug(断点调试)(IntelliJ IDEA 2022.1.3版本)

编程过程中如果出现错误&#xff0c;需要查找和定位错误时&#xff0c;借助程序调试可以快速查找错误。 编写好程序后&#xff0c;可能出现的情况&#xff1a; 1.没有bug。 使用Debug的情况&#xff1a; 2.运行后&#xff0c;出现错误或者异常信息&#xff0c;但是通过日志文件…

go的面向对象学习

文章目录 面向对象编程(上)1.问题与解决思路2.结构体1》Golang语言面向对象编程说明2》结构体与结构体变量(实例/对象)的关系的示意图3》入门案例(using struct to solve the problem of cat growing) 3.结构体的具体应用4.创建结构体变量和访问结构体字段5.struct类型的内存分…

vue3 组件v-model绑定props里的值,修改组件的值要触发回调

很早之前就写了&#xff0c;一直没写篇博客记录下 <select v-model"typeVal" />const emit defineEmits([update:type]); const props defineProps({type: { type: String, default: }, });const typeVal computed({get() {return props.type;},set(value…

Docker-compose创建LNMP服务并运行Wordpress网站平台

一、部署过程 1.安装Docker #关闭防火墙 systemctl stop firewalld.service setenforce 0#安装依赖包 yum install -y yum-utils device-mapper-persistent-data lvm2 #设置阿里云镜像源 yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/d…

17基于matlab卡尔曼滤波的行人跟踪算法,并给出算法估计误差结果,判断算法的跟踪精确性,程序已调通,可直接运行,基于MATLAB平台,可直接拍下。

17基于matlab卡尔曼滤波的行人跟踪算法&#xff0c;并给出算法估计误差结果&#xff0c;判断算法的跟踪精确性&#xff0c;程序已调通&#xff0c;可直接运行&#xff0c;基于MATLAB平台&#xff0c;可直接拍下。 17matlab卡尔曼滤波行人跟踪 (xiaohongshu.com)

如何设计一个安全的对外接口?

转载 https://blog.csdn.net/weixin_46742102/article/details/108831868?spm1001.2101.3001.6650.1&utm_mediumdistribute.pc_relevant.none-task-blog-2%7Edefault%7ECTRLIST%7ERate-1-108831868-blog-125359890.235%5Ev38%5Epc_relevant_anti_t3_base&depth_1-utm_…

Java中的枚举是什么?

Java枚举详解 枚举&#xff08;Enum&#xff09;是Java编程语言中的一种特殊数据类型&#xff0c;它用于表示一组具名的常量。枚举提供了一种更加类型安全和易于理解的方式来表示常量值&#xff0c;使代码更加清晰和可维护。 为什么需要枚举&#xff1f; 在介绍Java枚举的具…

你知道npm、yarn、pnpm的区别吗?

npm 嵌套的 node_modules 结构 npm 在早期采用的是嵌套的 node_modules 结构&#xff0c;“node_modules” 文件夹通常包含项目依赖的模块。在项目中使用多个依赖并且这些依赖本身也有它们自己的依赖时&#xff0c;就会出现嵌套的 “node_modules” 结构。 嵌套的 “node_mo…

【Redis学习1】Redis持久化机制详解

Redis持久化机制详解 一、Redis为什么需要持久化机制 Redis一般用作缓存&#xff0c;其数据存储在内存中&#xff0c;当Redis宕机后&#xff0c;内存中的数据将会丢失。因此使用缓存的时候&#xff0c;我们经常需要对内存中的数据进行持久化也就是将内存中的数据写入到硬盘中…

Jetpack:004-如何使用文本组件

文章目录 1. 概念介绍2. 使用方法2.1 通用参数2.2 专用参数 3. 示例代码4. 内容总结 我们在上一章回中介绍了Jetpack组件在布局中的对齐方式&#xff0c;本章回中主要介绍文 本组件的使用方法。闲话休提&#xff0c;让我们一起Talk Android Jetpack吧 1. 概念介绍 我们在本章…

YOLOv7改进:SPD-Conv,低分辨率图像和小物体涨点明显,涨点神器!!!

💡💡💡本文属于原创独家改进:SPD-Conv,优势:处理低分辨率图像和小物体等更困难的任务时性能更优 SPD-Conv | 亲测在多个数据集实现暴力涨点,尤其是小物体检测你值得拥有,强烈推荐,独家首发; 收录: YOLOv7高阶自研专栏介绍: http://t.csdnimg.cn/tYI0c ✨…

基于ffmpeg给视频添加时间字幕

FFmpeg是一套可以用来记录、转换数字音频、视频&#xff0c;并能将其转化为流的开源计算机程序&#xff0c;我们可以基于ffmpeg对视频进行各种操作。本文主要介绍基于ffmpeg给视频添加字幕&#xff0c;字幕的内容为视频所播放的时间&#xff08;故需要安装ffmpeg&#xff0c;具…

Stream 流式编程创建及其常用操作方法

目录 Stream 对象如何创建 Stream 常用的操作方法 1.过滤&#xff08;Filter&#xff09; 2.映射&#xff08;Map&#xff09; 3.扁平映射&#xff08;FlatMap&#xff09; 4.截断&#xff08;Limit&#xff09; 5.跳过&#xff08;Skip&#xff09; 6.排序&#xff08…

ssti 前置学习

python venv环境 可以把它想象成一个容器&#xff0c;该容器供你用来存放你的Python脚本以及安装各种Python第三方模块&#xff0c;容器里的环境和本机是完全分开的 创建venv环境安装flask #apt install python3.10-venv #cd /opt #python3 -m venv flask1 #cd /opt 选…

吃透底层:从路由到前缀树

前言 今天学到关于路由相关文章&#xff0c;发现动态路由中有一个很常见的实现方式是前缀树&#xff0c;很感兴趣这个算法&#xff0c;故进行记录。 前缀树 Trie&#xff08;又被叫做字典树&#xff09;可以看作是一个确定有限状态自动机&#xff0c;尽管边上的符号一般是隐含…

Netty通信在中间件组件中的广泛使用-Dubbo3举例

Netty是一个高性能异步IO通信框架&#xff0c;封装了NIO&#xff0c;对各种bug做了很好的优化解决。所以很多中间件底层的通信都会使用Netty&#xff0c;比如说&#xff1a;Dubbo3&#xff0c;rocketmq&#xff0c;ElasticSearch等。 比方说&#xff0c;我们使用dubbo作为rpc跨…

基于SSM线上课程管理系统设计与实现

末尾获取源码 开发语言&#xff1a;Java Java开发工具&#xff1a;JDK1.8 后端框架&#xff1a;SSM 前端&#xff1a;采用JSP技术开发 数据库&#xff1a;MySQL5.7和Navicat管理工具结合 服务器&#xff1a;Tomcat8.5 开发软件&#xff1a;IDEA / Eclipse 是否Maven项目&#x…