Swagger 概念和使用以及遇到的问题

前言

        接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变
成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,
导致前端人员抱怨接口文档和实际情况不一致。
        很多人员会抱怨别人写的接口文档不规范,不及时更新。但是当自己写的时候确实最烦
去写接口文档。这种痛苦只有亲身经历才会牢记于心。
        如果接口文档可以实时动态生成就不会出现上面问题。
        Swagger可以完美的解决上面的问题。

Open API 是什么

         Open API规范(OpenAPI Specification)以前叫做 Swagger 规范,是 REST API 的API
描述格式。
Open API 文件允许描述整个API,包括︰
● 每个访问地址的类型。POST 或 GET。I
● 每个操作的参数。包括输入输出参数。
● 认证方法。
● 连接信息,声明,使用团队和其他信息。
        Open API 规范可以使用 YAML 或 JSON 格式进行编写。这样更利于我们和机器进行
阅读。

        OpenAPI规范 (OAS ) 为 REST API 定义了一个与语言无关的标准接口,允许人和计
算机发现和理解服务的功能,而无需访问源代码,文档或通过网络流量检查。正确定义后,
消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。
        然后,文档生成工具可以使用 OpenAPI 定义来显示 API ,使用各种编程语言生成服务
器和客户端的代码生成工具,测试工具以及许多其他用例。

       

个人理解:Swagger 可以自动的将代码转换成  YAML 或 JSON 格式的接口文档,确保接口文档的实时更新,并且减少写接口文档的痛苦。

swagger 的使用

        在中心仓库搜索 springfox-swagger2,直接使用 swagger 不方便,springfox 对 swagger 进行了封装,可以更方便的使用。

链接:https://mvnrepository.com/artifact/io.springfox/springfox-swagger2

        向 Spring 项目中添加 springfox-swagger2 依赖:

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency>

        再向项目中添加视图逻辑,这样才可以生成方便查看的接口文档。

        在中心仓库搜索 springfox-swagger-ui

 链接:https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

向 Spring 项目中添加 springfox-swagger-ui 依赖:

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

@EnableSwagger2

        @EnableSwagger2 是 springfox 提供的一个注解,代表 swagger2 相关技术开启。 加上该注解后会扫描当前类所在包,以及子包中所有类的注解,做 swagger 文档的定值,一般加在启动类上

/*** @EnableSwagger2 是 springfox 提供的一个注解,代表 swagger2 相关技术开启。* 会扫描当前类所在包,以及子包中所有类的注解,做 swagger 文档的定值* */
@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {public static void main(String[] args) {SpringApplication.run(SwaggerApplication.class, args);}
}

        一般情况下加上 @EnableSwagger2 后就可以直接访问 http://localhost:8080/swagger-ui.html 查看 swagger ui 的界面了

        但是博主遇到了两个问题,一个是直接报错无法运行,一个是 查看 swagger ui 的界面是 404

错误

直接报错无法运行

        此时博主直接尝试运行遇到了一个错误

        这个问题通常发生在 Spring Boot 2.6 及以上版本中,当整合 Swagger 时,由于Spring MVC的路径匹配策略变更导致的兼容性问题。在Spring Boot 2.6版本之后,默认的路径匹配策略由AntPathMatcher 改为了 PathPatternParser,而Swagger(Springfox)仍然使用AntPathMatcher,这就导致了冲突。

        我通过下面的办法解决了问题:

        修改路径匹配策略:在 application.properties 或 application.yml 配置文件中,添加以下配置来指定使用 AntPathMatcher 作为路径匹配策略:

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

查看 swagger ui 的界面是 404

        我们需要创建一个 SwaggerConfig 配置类,在配置类中添加如下配置:

package com.example.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @author 全栈学习笔记* @date 2020/4/19 16:00* @description*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)// 指定构建api文档的详细信息的方法:apiInfo().apiInfo(apiInfo()).select()// 指定要生成api接口的包路径.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))//使用了 @ApiOperation 注解的方法生成api接口文档//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档,忽略哪些请求.build();}/*** 设置api文档的详细信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder()// 标题.title("Spring Boot集成Swagger2")// 接口描述.description("swagger")// 版本信息.version("1.0")// 构建.build();}
}

        就可以正常访问到我们的 swagger ui 界面了

使用 swagger ui 检查接口是否正确

        首先我们先写一些接口类:

@RestController
public class MyController {@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(String id,String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        注意:要在 SwaggerConfig 配置类中加上 MyController  类的包名

        再次访问 swagger ui 界面可以看到已经有了接口信息

        点击一个接口我们可以看到该接口的详细信息,点击 Try it out 可以发起请求检测接口的返回信息

        在方框中输入要传递的参数值 id=1

        点击 Execute 发送请求

        在下面的信息栏就可以查看接口返回的信息,判断接口是否正常工作

swagger 常用注解

@Api 描述类

        用于描述当前类型生成帮助文档的信息(该注解只能用于类上)

属性:

        tags :给当前类型定义别名,可以定义多个。定义几个别名,就在 ui 视图中显示几个控制器访问菜单。

        description :给当前类型生成的帮助文档定义一个描述信息(已经过时了)

@RestController
@RequestMapping("/MyController")
/*** @Api - 描述当前类型生成帮助文档的信息* 属性-*  - tags :给当前类型定义别名,可以定义多个。定义几个别名,就在 ui 视图中显示几个控制器访问菜单。*  - description :给当前类型生成的帮助文档定义一个描述信息(已经过时了)* */
@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(String id,String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        可以看到给 MyController 类设置别名后出现了一个新的控制器访问菜单

@ApiOperation 描述方法

        用于描述方法的信息(该注解可以用于类上和方法上,但通常用于方法上)

属性:

        value:对方法的描述信息

        notes:对方法的提示信息 (两个属性的信息所在位置不同)

@RestController
@RequestMapping("/MyController")@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@ApiOperation(value = "get方法,获取客户 id ",notes = "swagger 学习使用 - 处理 GET 请求的方法")@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(String id,String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        如下图,get 方法后有描述信息,post 方法后没有描述信息

点开接口详情,可以看到对该接口的提示信息

@ApiParam 描述参数

        用于描述参数的信息

属性:

        name:参数名称

        value:对参数的描述信息

        required:该参数是否必须(默认是 false)

@RestController
@RequestMapping("/MyController")@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@ApiOperation(value = "get方法,获取客户 id ",notes = "swagger 学习使用 - 处理 GET 请求的方法")@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(@ApiParam(name = "用户 id ",value = "新增用户时用的用户 id ",required = true) String id,@ApiParam(name = "用户名",value = "新增用户时用的用户名",required = true) String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        可以看到属性有了详细的描述信息

@ApiIgnore 忽略

        忽略该注解描述的方法和类,不生产 api 帮助文档

    // @ApiIgnore - 忽略该注解描述的方法和类,不生成 api 帮助文档@ApiIgnore@RequestMapping("/req")public String req(){return "req";}

        如同,添加后由 RequestMapping 产生的多个接口的文档都消失了

@ApiImplicitParams 在方法前描述参数

        在方法前描述参数。

属性:

        name:参数名称

        value:对参数的描述信息

        required:该参数是否必须(默认是 false)

        paramType:该参数的类型

@RestController
@RequestMapping("/MyController")@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@ApiOperation(value = "get方法,获取客户 id ",notes = "swagger 学习使用 - 处理 GET 请求的方法")@GetMapping("/get")@ApiImplicitParams(value = {@ApiImplicitParam(name = "id",value = "前端获取用户id",paramType = "int",required = true),@ApiImplicitParam(name = "name",value = "前端获取用户名",paramType = "字符串")})public String get(String id,String name){return "get";}@PostMapping("/post")public String post(@ApiParam(name = "用户 id ",value = "新增用户时用的用户 id ",required = true) String id,@ApiParam(name = "用户名",value = "新增用户时用的用户名",required = true) String name){return "post";}// @ApiIgnore - 忽略该注解描述的方法和类,不生成 api 帮助文档@ApiIgnore@RequestMapping("/req")public String req(){return "req";}
}

        作用和 @ApiParam 相同,只是写在方法上而已

@ApiModel 与 @ApiModelProperty 描述实体类型

        @ApiModel 与 @ApiModelProperty 描述实体类型,这个实体类型如果成为了接口的返回类型并且该接口生成了接口文档,那么此注解会被解析,生成描述实体类型的文档

@ApiModel(value = "学生实体 - Student ",description = "存储学生信息")
public class Student{@ApiModelProperty(value = "主键",name = "主键(id)",required = true,example = "q",hidden = false)private String id;  //主键@ApiModelProperty(value = "姓名",name = "姓名(name)",required = true,example = "张三",hidden = false)private String name;    //姓名@ApiModelProperty(value = "密码",name = "密码(password)",required = true,example = "123456",hidden = false)private String password;    //密码public Student(){};public String getId() {return id;}public void setId(String id) {this.id = id;}public String getName() {return name;}public void setName(String name) {this.name = name;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}
}
    @GetMapping("/getStudentInfo")public Student getStudentInfo(){return new Student();}

        如图,可以查看实体的详细信息

@ApiModel

        描述实体类

属性:

        value:该实体的名称

        description:该实体的描述

@ApiModelProperty

        描述实体类的属性

属性:

        name:属性的名称

        value:属性的描述

        required:是否必须

        example:示例

        hidden:是否隐藏

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

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

相关文章

从黎巴嫩电子通信设备爆炸看如何防范网络电子袭击

引言&#xff1a; 在当今数字化时代&#xff0c;电子通信设备已成为我们日常生活中不可或缺的一部分。然而&#xff0c;近期黎巴嫩发生的电子设备爆炸事件提醒我们&#xff0c;这些设备也可能成为危险的武器。本文将深入探讨电子袭击的原理、防范措施&#xff0c;以及网络智能…

【论文阅读】Face2Diffusion for Fast and Editable Face Personalization

code&#xff1a;mapooon/Face2Diffusion: [CVPR 2024] Face2Diffusion for Fast and Editable Face Personalization https://arxiv.org/abs/2403.05094 (github.com) 论文 介绍 目标&#xff1a;向 T2I 模型不知道的图像中插入特定概念&#xff08;例如某人的脸&#xff…

极狐GitLab 重要安全版本:17.3.3, 17.2.7, 17.1.8, 17.0.8, 16.11.10

GitLab 是一个全球知名的一体化 DevOps 平台&#xff0c;很多人都通过私有化部署 GitLab 来进行源代码托管。极狐GitLab 是 GitLab 在中国的发行版&#xff0c;专门为中国程序员服务。可以一键式部署极狐GitLab。 学习极狐GitLab 的相关资料&#xff1a; 极狐GitLab 官网极狐…

通过logstash同步elasticsearch数据

1 概述 logstash是一个对数据进行抽取、转换、输出的工具&#xff0c;能对接多种数据源和目标数据。本文介绍通过它来同步elasticsearch的数据。 2 环境 实验仅仅需要一台logstash机器和两台elasticsearch机器&#xff08;elasticsearch v7.1.0&#xff09;。本文用docker来模…

css 样式简单学习(一)

目录 1. css 介绍 1.1 css 样式 1.2 css代码风格 1.2.1 书写格式 1.2.2 样式大小写​编辑 1.2.3 空格规范 2. 基础选择器 2.1 选择器的作用​编辑 2.2 选择器的分类 2.3 基础选择器 2.3.1 标签选择器​编辑 2.3.2 类选择器​编辑 2.3.3 类选择器-多类名​编辑 2.…

简单题88. 合并两个有序数组 (Python)20240920

问题描述&#xff1a; python&#xff1a; class Solution(object):def merge(self, nums1, m, nums2, n):""":type nums1: List[int]:type m: int:type nums2: List[int]:type n: int:rtype: None Do not return anything, modify nums1 in-place instead.&qu…

选址模型 | 基于混沌模拟退火粒子群优化算法的电动汽车充电站选址与定容(Matlab)

目录 效果一览基本介绍程序设计参考资料 效果一览 基本介绍 基于混沌模拟退火粒子群优化算法的电动汽车充电站选址与定容&#xff08;Matlab&#xff09; 问题建模&#xff1a;首先&#xff0c;需要将电动汽车充电站选址与定容问题进行数学建模&#xff0c;确定目标函数和约束…

React18入门教程

React介绍 React由Meta公司开发&#xff0c;是一个用于 构建Web和原生交互界面的库 React的优势 相较于传统基于DOM开发的优势 组件化的开发方式 不错的性能 相较于其它前端框架的优势 丰富的生态 跨平台支持 React的市场情况 全球最流行&#xff0c;大厂必备 开发环境…

【Verilog学习日常】—牛客网刷题—Verilog快速入门—VL24

边沿检测 有一个缓慢变化的1bit信号a&#xff0c;编写一个程序检测a信号的上升沿给出指示信号rise&#xff0c;当a信号出现下降沿时给出指示信号down。 注&#xff1a;rise,down应为单脉冲信号&#xff0c;在相应边沿出现时的下一个时钟为高&#xff0c;之后恢复到0&#xff0…

密集行人数据集 CrowdHumanvoc和yolo两种格式,yolo可以直接使用train val test已经划分好有yolov8训练200轮模型

密集行人数据集 CrowdHuman voc和yolo两种格式&#xff0c;yolo可以直接使用 train val test已经划分好 有yolov8训练200轮模型。 CrowdHuman 密集行人检测数据集 数据集描述 CrowdHuman数据集是一个专为密集行人检测设计的数据集&#xff0c;旨在解决行人密集场景下的检测挑…

关于实时数仓的几点技术分享

一、实时数仓建设背景 业务需求的变化&#xff1a;随着互联网和移动互联网的快速发展&#xff0c;企业的业务需求变得越来越复杂和多样化&#xff0c;对数据处理的速度和质量要求也越来越高。传统的T1数据处理模式已经无法满足企业的需求&#xff0c;实时数据处理成为了一种必…

什么是 IP 地址信誉?5 种改进方法

IP 地址声誉是营销中广泛使用的概念。它衡量 IP 地址的质量&#xff0c;这意味着您的电子邮件进入垃圾邮件或被完全阻止发送的可能性。 由于每个人都使用专用电子邮件提供商而不是直接通过 IP 地址进行通信&#xff0c;因此&#xff0c;这些服务可以跟踪和衡量发件人的行为质量…

表情包创作、取图小程序端(带流量主)

小程序永久免费&#xff0c;无任何广告&#xff0c;无任何违规功能&#xff01; 小程序具备以下功能有&#xff1a; 支持创作者加入 支持在线制作表情包 使用说明 表情包必备工具&#xff0c;一款专属于你的制作表情包工具&#xff0c;斗图必备神器

Linux下进程通信与FIFO操作详解

Linux下进程通信与FIFO操作详解 一、命名管道(FIFO)概述1.1 命名管道的特点1.2 创建命名管道二、命名管道的操作2.1 打开命名管道2.2 读写命名管道2.3 关闭命名管道三、命名管道的使用实例3.1 命名管道的创建和通信过程3.1.1 发送方(writer)3.1.2 接收方(reader)3.2 运行…

python 爬虫 selenium 笔记

todo 阅读并熟悉 Xpath, 这个与 Selenium 密切相关、 selenium selenium 加入无图模式&#xff0c;速度快很多。 from selenium import webdriver from selenium.webdriver.chrome.options import Options# selenium 无图模式&#xff0c;速度快很多。 option Options() o…

Qt/C++事件过滤器与控件响应重写的使用、场景的不同

在Qt/C中&#xff0c;事件过滤器和控件响应重写是两种用于捕获和处理鼠标、键盘等事件的机制&#xff0c;它们的用途和使用场景不同&#xff0c;各有优劣。下面详细介绍它们的区别、各自适用的场景、以及混合使用的场景和注意事项。 1. 事件过滤器&#xff08;Event Filter&…

全能OCR神器GOT-OCR2.0整合包部署教程

项目地址:https://github.com/Ucas-HaoranWei/GOT-OCR2.0 整合包下载&#xff1a;https://pan.quark.cn/s/3757da820e65 显卡建议使用RTX 30以上的 ①先安装NVIDIA显卡驱动&#xff1a; https://www.nvidia.cn/drivers/lookup/ 输入显卡型号搜索就行 ②安装CUDA 工具包 cu…

Django 聚合查询

文章目录 一、聚合查询二、使用步骤1.准备工作2.具体使用3.分组查询&#xff08;annotate&#xff09;1.定义2.使用3.具体案例 4.F() 查询1.定义2.使用 5.Q() 查询1.定义2.查询 一、聚合查询 使用聚合查询前要先从 django.db.models 引入 Avg、Max、Min、Count、Sum&#xff0…

力扣 2529.正整数和负整数的最大计数

文章目录 题目介绍解法 题目介绍 解法 采用红蓝染色体法&#xff0c;具体介绍参考 红蓝染色体法 通过红蓝染色体法可以找到第一个大于大于target的位置&#xff0c;使所以本题可以找第一个大于0的位置&#xff0c;即负整数的个数&#xff1b;数组长度 - 第一个大于1的位置即正…

【踩坑】装了显卡,如何让显示器从主板和显卡HDMI都输出

转载请注明出处&#xff1a;小锋学长生活大爆炸[xfxuezhagn.cn] 如果本文帮助到了你&#xff0c;欢迎[点赞、收藏、关注]哦~ 背景介绍 装了显卡后&#xff0c;开机默认是从显卡的HDMI输出&#xff0c;但这很不方便。如何让视频仍然从主板输出&#xff1f;或者说让显卡HDMI和主板…