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.rhkb.cn/news/153076.html

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

相关文章

Linux命令基本用法

1.用户相关命令 1.账号管理 命令作用useradd添加用户passwd设置密码usermod修改用户userdel删除用户su切换用户 例&#xff1a; [rootlocalhost ~]# useradd aaa [rootlocalhost ~]# su aaa [aaalocalhost root]$ su root 密码&#xff1a; [rootlocalhost ~]# passwd aaa …

Android系统定制之监听USB键盘来判断是否弹出软键盘

一.项目背景 在设备上弹出软键盘,会将一大部分UI遮挡起来,造成很多图标无法看到和点击,使用起来不方便,因此通过插入usb键盘输入代替软键盘,但是点击输入框默认会弹出软键盘,因此想要插入USB键盘时,默认关闭软键盘,拔出键盘时再弹出,方便用户使用 二.设计思路 2.1…

【TES720D-KIT】青翼科技支持双网口的全国产化四核CPU+FPGA处理器开发套件

TES720D-KIT是专门针对我司TES710D&#xff08;基于复旦微FMQL10S400的全国产化ARM核心板&#xff09;的一套开发套件&#xff0c;它包含1个TES720D核心板&#xff0c;加上一个TES720D-EXT扩展底板。 FMQL20S400是复旦微电子研制的全可编程融合芯片&#xff0c;在单芯片内集成…

Docker私有仓库打开2375端口(linux)

前言 在我们开发测试过程中&#xff0c;需要频繁的更新docker镜像&#xff0c;然而默认情况下&#xff0c;docker的2375端口是关闭的&#xff0c;下面介绍如何打开端口。 1、打开步骤 1.1、修改配置 登录docker所在服务器&#xff0c;修改docker.service文件 vi /usr/lib/sys…

Altium Designer实用系列(二)----PCB绘图小技巧

一、技巧总结 1.1 丝印大小 在导入PCB之后&#xff0c;元器件的丝印一般都是strock font&#xff0c;个人感觉比较大&#xff0c;也不美观&#xff0c;但是一个个修改成true type又比较麻烦。简便方法是使用相似查找全部修改:   此时会选中所有stroke 类型的丝印&#xff…

2.1 Qemu系统模拟:简介

目录 1 后端/加速器2 特性简介3 运行 1 后端/加速器 系统模拟主要用于在host设备上运行guest OSQEMU支持多种hypervisors,同时也支持JIT模拟方案&#xff08;TCG&#xff09; 例如从上表我们可以看出&#xff0c;运行在x86硬件上的Linux系统支持KVM,Xen,TCG 2 特性简介 提供…

最新AI创作系统/AI绘画系统/ChatGPT系统+H5源码+微信公众号版+支持Prompt应用

一、AI创作系统 SparkAi创作系统是基于国外很火的ChatGPT进行开发的AI智能问答系统和AI绘画系统。本期针对源码系统整体测试下来非常完美&#xff0c;可以说SparkAi是目前国内一款的ChatGPT对接OpenAI软件系统。那么如何搭建部署AI创作ChatGPT&#xff1f;小编这里写一个详细图…

教资面试多烂才不合格 教师资格证面试难度分析

教资面试是否合格&#xff0c;主要取决于考生的表现是否符合教师职业要求和教育教学能力。以下是一些可能导致教资面试不合格的表现&#xff1a; 对教育事业缺乏热情&#xff0c;对所教授的学科不感兴趣&#xff0c;或者对教育工作没有正确的认知。 对学生的关注不足&#xf…

GG-Net: 超声图像中乳腺病变分割的全局指导网络

ATTransUNet 期刊分析摘要贡献方法整体框架1. Global Guidance Block2. Spatial-wise Global Guidance Block3. Channel-wise Global Guidance Block4. Breast Lesion Boundary Detection Module 实验1. 对比实验2. 消融实验2.1 Ablation Analysis of our GG-Net2.2 Ablation A…

STM32--基于STM32的智能家居设计与实现

本文详细介绍基于STM32F103C8T6的智能家居设计与实现&#xff0c;详细设计资料见文末链接 一、功能模块介绍 智能家居系统系统图如下所示&#xff0c;主要包括温湿度传感器、OLED液晶显示&#xff0c;WIFI物联网模块、人体红外预警模块、烟雾传感器模块、蜂鸣器模块 &#…

剑指offer——JZ86 在二叉树中找到两个节点的最近公共祖先 解题思路与具体代码【C++】

一、题目描述与要求 在二叉树中找到两个节点的最近公共祖先_牛客题霸_牛客网 (nowcoder.com) 题目描述 给定一棵二叉树(保证非空)以及这棵树上的两个节点对应的val值 o1 和 o2&#xff0c;请找到 o1 和 o2 的最近公共祖先节点。 数据范围&#xff1a;树上节点数满足1≤n≤1…

UE5修改导航网格的参数

Unreal Engine 4 - Recast NavMesh Size, how to Change Agent Radius / Tutorial - YouTubehttps://www.youtube.com/watch?vf3hF6xdmCTk 修改当前的 代理半径就是一般贴边的长度 修改编辑器的

deckGL自定义图层学习笔记

1.自定义图层 当使用DeckGL提供的图层还无法满足需求时&#xff08;https://deck.gl/docs/api-reference/layers&#xff09;&#xff0c;可能就需要自定义图层了。在DeckGL中有常见的三种自定义图层的方式 创建复合层&#xff08;composite layers.&#xff09;——复合层是一…

建立数据科学基础设施的绝佳指南 数据工程师都该人手一册

《Effective数据科学基础设施》由Netflix工程师Ville Tuulos撰写&#xff0c;以Metaflow为对象&#xff0c;介绍了数据科学所需要的基础设施&#xff0c;囊括数据准备、特征工程、模型训练、模型部署、服务和持续监控等环节。Metaflow专注于构建生产流程&#xff0c;更适合具有…

最新AI创作系统源码ChatGPT网站源码V2.6.3/支持Midjourney绘画/支持OpenAI GPT全模型+国内AI全模型

一、AI创作系统 SparkAi创作系统是基于OpenAI很火的ChatGPT进行开发的Ai智能问答系统&#xff0c;支持OpenAI GPT全模型国内AI全模型。本期针对源码系统整体测试下来非常完美&#xff0c;可以说SparkAi是目前国内一款的ChatGPT对接OpenAI软件系统。那么如何搭建部署AI创作Chat…

想要开发一款游戏, 需要注意什么?

开发一款游戏是一个复杂而令人兴奋的过程。游戏开发是指创建、设计、制作和发布电子游戏的过程。它涵盖了从最初的概念和创意阶段到最终的游戏发布和维护阶段的各个方面。 以下是一些需要注意的关键事项&#xff1a; 游戏概念和目标&#xff1a; 确定游戏开发的核心概念和目标…

小视频APP源码选择指南:挑选最适合你的开发框架

在如今蓬勃发展的小视频APP行业中&#xff0c;源码的选择是打造一款成功应用的关键步骤。然而&#xff0c;面对众多开发框架的选择&#xff0c;如何挑选最适合你的小视频APP源码呢&#xff1f;作为这一领域的专家&#xff0c;我将为你提供一份详尽的指南&#xff0c;助你在源码…

nginx-proxy反向代理缓存

介绍&#xff1a; 反向代理缓存&#xff0c;类似于动静分离&#xff0c;即通过nginx代理服务器根据客户端发送的url请求&#xff0c;去后台服务器获取数据&#xff0c;将静态数据缓存到nginx代理服务器上&#xff0c;并配置有过期时间&#xff0c;当客户端下次以相同的url请求…

LVS+Keepalived 高可用集群负载均衡

一.keepalived介绍 1.1.Keepalived实现原理 由多台路由器组成一个热备组&#xff0c;通过共用的虚拟IP地址对外提供服务。 每个热备组内同时只有一台主路由器提供服务&#xff0c;其他路由器处于冗余状态。 若当前在线的路由器失效&#xff0c;则其他路由器会根据设置…

【Python查找算法】二分查找、线性查找、哈希查找

目录 1 二分查找算法 2 线性查找算法 3 哈希查找算法 1 二分查找算法 二分查找&#xff08;Binary Search&#xff09;是一种用于在有序数据集合中查找特定元素的高效算法。它的工作原理基于将数据集合分成两半&#xff0c;然后逐步缩小搜索范围&#xff0c;直到找到目标元素…