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.hqwc.cn/news/129378.html

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

相关文章

【Node.js】URL 模块

【Node.js】URL 模块

自动重启服务器的插件nodemon&#xff1a; npm i -g nodemon。或者 node-dev 也可以&#xff1a;npm i -g node-dev。 parse&#xff0c;format&#xff0c;resolve 为旧版写法。 parse import url from url const urlString https://www.baidu.com:443/ad/index.html?id8&a…
阅读更多...
Java8实战-总结39

Java8实战-总结39

Java8实战-总结39 默认方法解决冲突的规则解决问题的三条规则选择提供了最具体实现的默认方法的接口冲突及如何显式地消除歧义菱形继承问题 小结 默认方法 解决冲突的规则 Java语言中一个类只能继承一个父类&#xff0c;但是一个类可以实现多个接口。随着默认方法在Java 8中引…
阅读更多...
arm-三盏灯流水

arm-三盏灯流水

.text .global _start _start: 1.设置GPIOE寄存器的时钟使能 RCC_MP_AHB4ENSETR[4]->1 0x50000a28 LDR R0,0x50000A28 LDR R1,[R0] ORR R1,R1,#(0x3<<4) 第四位第五位都设置为1 STR R1,[R0] 写回2.设置PE10管脚为输出模式 GPIOE_MODER[21:20]->01 0x5000…
阅读更多...
数据结构和算法——线性结构

数据结构和算法——线性结构

文章目录 前言线性表顺序表链表合并有序链表反转链表 队列循环队列双端队列资源分配问题 栈共享栈表达式求值递归处理迷宫问题 串串的模式匹配BF算法KMP算法next数组的求解next数组的优化 前言 本文所有代码均在仓库中&#xff0c;这是一个完整的由纯C语言实现的可以存储任意类…
阅读更多...
【MySQL】基本查询（三）聚合函数+group by

【MySQL】基本查询（三）聚合函数+group by

文章目录 一. 聚合函数二. group by子句结束语 建立如下表 //创建表结构 mysql> create table exam_result(-> id int unsigned primary key auto_increment,-> name varchar(20) not null comment 同学姓名,-> chinese float default 0.0 comment 语文成绩,->…
阅读更多...
Go 语言中 panic 和 recover 搭配使用

Go 语言中 panic 和 recover 搭配使用

本次主要聊聊 Go 语言中关于 panic 和 recover 搭配使用 &#xff0c;以及 panic 的基本原理 最近工作中审查代码的时候发现一段代码&#xff0c;类似于如下这样&#xff0c;将 recover 放到一个子协程里面&#xff0c;期望去捕获主协程的程序异常 看到此处&#xff0c;是否会…
阅读更多...
内网渗透之哈希传递

内网渗透之哈希传递

文章目录 哈希传递&#xff08;NTLM哈希&#xff09;概念LMNTLM 原理利用hash传递获取域控RDP 总结 哈希传递&#xff08;NTLM哈希&#xff09; 内网渗透中找到域控IP后使用什么攻击手法拿下域控&#xff1a; 扫描域控开放端口。因为域控会开放远程连接&#xff1a;windows开…
阅读更多...
常见排序算法Java版（待续）

常见排序算法Java版（待续）

冒泡排序O(n^2) public class Main {public static void main(String[] args) {Random random new Random();int[] nums new int[]{random.nextInt(100), random.nextInt(100), random.nextInt(100), random.nextInt(100), random.nextInt(100), random.nextInt(100)};for (i…
阅读更多...
SQL Server 简介与 Docker Compose 部署

SQL Server 简介与 Docker Compose 部署

今天我翻阅了在之前公司工作时的笔记&#xff0c;发现了有关数据库的一些记录。当时&#xff0c;我们的项目开始使用 Oracle 数据库&#xff0c;但后来由于一些项目需求的变更&#xff0c;我们切换到了 SQL Server 。值得一提的是&#xff0c;公司当时也开始采用 Docker 技术&a…
阅读更多...
多路彩灯控制器led流水灯VHDL速度可调仿真图视频、源代码

多路彩灯控制器led流水灯VHDL速度可调仿真图视频、源代码

名称&#xff1a;多路彩灯控制器led流水灯VHDL速度可调 软件&#xff1a;Quartus 语言&#xff1a;VHDL 代码功能&#xff1a; 使用VHDL设计彩灯控制器&#xff0c;共24个led灯&#xff0c;分为5种不同的花样&#xff0c;可以通过按键切换花样的变化速度。 代码下载&#…
阅读更多...
设计模式 - 行为型模式：策略模式（概述 | 案例实现 | 优缺点 | 使用场景）

设计模式 - 行为型模式：策略模式（概述 | 案例实现 | 优缺点 | 使用场景）

目录 一、行为型模式 1.1、策略模式 1.1.1、概论 1.1.2、案例实现 1.1.3、优缺点 1.1.4、使用场景 一、行为型模式 1.1、策略模式 1.1.1、概论 策略模式设计的每一个算法都封装了起来&#xff0c;使他们可以相互替换&#xff0c;通过一个对象委派不同的算法给相应的客户…
阅读更多...
vscode ssh linux C++ 程序调试

vscode ssh linux C++ 程序调试

vscode调试c++程序相比vs2022要复杂很多，vs2022可以"一键运行调试"，vscode则需要自己配置。 ​vscode调试程序时，会在当前工作目录产生.vscode 目录， 该目录有两个重要文件launch.json和tasks.json, 下面介绍两种调试方法: 手动调试和自动调试。 手动调试 不管…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023