Swagger 的介绍以及使用

文章目录

  • Swagger
    • 一.导语：
    • 二.Swagger是什么？它能干什么？
        • 框架说明
        • 总结:
        • 作用
    • 三.SpringBoot集成Swagger
      • 3.1初始实现步骤
      • 3.2配置Swagger
      • 3.3配置扫描接口
      • 3.4配置API分组
      • 3.5拓展：其他皮肤
    • 四.常用注解

Swagger

一.导语：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了

二.Swagger是什么？它能干什么？

https://swagger.io/

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

框架说明

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：

Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。其实swagger是有两个版本的，区别还挺大的，一个是swagger-ui也就是swagger1;还有一个是springfox-swagger也就是swagger2;

总结:

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用

  1. 接口的文档在线自动生成

  2. 功能测试

三.SpringBoot集成Swagger

3.1初始实现步骤

1.添加Maven依赖

<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>

当SpringBoot版本较高时，需要在yml文件中加一句

spring.mvc.pathmatch.matching-startegy=ANT_PATH_NATCHER

2.编写HelloController，测试确保运行成功

3.编写一个配置类-SwaggerConfig来配置 Swagger

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

4.访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

注意:

如果启动报错空指针是因为springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错

可以在启动类上加上@EnableWebMvc注解或者在配置中切换为原先的AntPathMatcher

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

3.2配置Swagger

1.Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2);
}

2.可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");return new ApiInfo("Swagger学习", // 标题"学习演示如何配置Swagger", // 描述"v1.0", // 版本"http://apesource.com", // 组织链接contact, // 联系人信息"Apach 2.0 许可", // 许可"许可链接", // 许可连接new ArrayList<>()// 扩展);}

3.Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4.重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

3.3配置扫描接口

1.构建Docket时通过select()方法配置怎么扫描接口

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller")).build();
}

2.重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

3.除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式

any() 			// 扫描所有，项目中的所有接口都会被扫描到
none() 			// 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

4.除此之外，我们还可以配置接口扫描过滤

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))// 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口.paths(PathSelectors.ant("/apesource/**")).build();
}

5.这里的可选值还有

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

3.4配置API分组

1.如果没有配置分组，默认是default。通过groupName()方法即可配置分组

@Bean
public Docket docket(Environment environment) {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("hello") // 配置分组// 省略配置....
}

2.重启项目查看分组

3.如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

3.5拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义

1.默认的访问 http://localhost:8080/swagger-ui.html

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

2.bootstrap-ui 访问 http://localhost:8080/doc.html

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.1</version>
</dependency>

四.常用注解

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

  • @Api：修饰整个类，描述Controller的作用

    语法：@Api(tags=“说明该类的作用，可以在UI界面上看到的注解”，value = “/类的访问路径”, description = “类的文字描述”)

  • @ApiOperation：描述一个类的一个方法，说明方法的作用

    语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

  • @ApiImplicitParam：一个请求参数

    语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”

    ​ · header --> 请求参数的获取：@RequestHeader
    ​ · query --> 请求参数的获取：@RequestParam
    ​ · path（用于restful接口）–> 请求参数的获取：@PathVariable
    ​ · body（不常用）
    ​ · form（不常用）

    ）

  • @ApiImplicitParams： 多个请求参数

  • @ApiParam：单个参数描述

    语法：@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

  • @ApiResponse：HTTP响应其中1个描述,响应配置

    语法：@ApiResponse(code = 400, message = “Invalid user supplied”)

  • @ApiResponses：HTTP响应整体描述

    语法：@ApiResponses({ @ApiResponse(code = 400, message = “Invalid Order”) })

  • @ApiModel：用对象实体来作为入参

  • @ApiProperty：用对象接实体收参数时，描述对象的一个字段

  • @ApiIgnore：使用该注解忽略这个API

  • @ApiError ：发生错误返回的信息

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

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

相关文章

Using Multiple RDF Knowledge Graphs for Enriching ChatGPT Responses

Using Multiple RDF Knowledge Graphs for Enriching ChatGPT Responses

本文是LLM系列文章&#xff0c;针对《Using Multiple RDF Knowledge Graphs for Enriching ChatGPT Responses》的翻译。 使用多个RDF知识图来丰富ChatGPT响应 摘要1 引言2 相关工作3 GPT-LODS的过程和用例4 结束语 摘要 最近有一种趋势是使用新型人工智能聊天GPT聊天箱&…
阅读更多...
ChatGPT集锦

ChatGPT集锦

目录 1. 一条指令让ChatGPT变的更强大2. 对ChatGPT提问时，常见的10种错误描述3. Custom instructions如何设置1. 一条指令让ChatGPT变的更强大 在使用GPT的过程中，如何让AI更清晰地了解你的需求很重要？今天分享一个指令，可以让GPT成为你的好同事，与你一起分析和解决问题，…
阅读更多...
Vue 项目开发将数据下载到本地的方法

Vue 项目开发将数据下载到本地的方法

将数据保存到本地 需求分析 需求 Vue 项目开发时&#xff0c;要求不调用接口下载&#xff0c;而是主动将接口多次调用产生的接口返回值讲过保存保存到本地 分析 需要使用浏览器的File API&#xff0c;本地存储多次接口返回的数据&#xff0c;在这里我使用的Vuex状态管理去存…
阅读更多...
linux - 文件利用率快满了 - mongo日志

linux - 文件利用率快满了 - mongo日志

https://zhuanlan.zhihu.com/p/82430795 查看文件利用率 df -h 文件夹大小 ls -lh 逐级搜索大文件或目录 du -sh * cd .. 返回上一层 ps -ef | grep mongo 启动&#xff1a; .mongodb/bin/mongod -f mongodb/config/configsvr.conf 关闭 .mongodb/bin/mongod -f mong…
阅读更多...
C# Winform 简单排期实现（DevExpress TreeList）

C# Winform 简单排期实现（DevExpress TreeList）

排期的需求在很多任务安排的系统中都有相应的需求&#xff0c;原生的Winform控件并未提供相应的控件&#xff0c;一般都是利用DataGridViewTreeView组合完成相应的需求&#xff0c;实现起来比较麻烦。用过DevExpress控件集的开发者应该知道&#xff0c;DevExpress WinForm提供了…
阅读更多...
【动态规划刷题 10】等差数列划分 最长湍流子数组

【动态规划刷题 10】等差数列划分 最长湍流子数组

413. 等差数列划分 链接: 413. 等差数列划分 如果一个数列 至少有三个元素 &#xff0c;并且任意两个相邻元素之差相同&#xff0c;则称该数列为等差数列。 例如&#xff0c;[1,3,5,7,9]、[7,7,7,7] 和 [3,-1,-5,-9] 都是等差数列。 给你一个整数数组 nums &#xff0c;返回…
阅读更多...
9.7黄金是否会继续下跌？后市如何布局

9.7黄金是否会继续下跌？后市如何布局

近期有哪些消息面影响黄金走势&#xff1f;今日黄金多空该如何研判&#xff1f; ​黄金消息面解析&#xff1a;周四(9月7日)亚市早盘&#xff0c;现货黄金继续承压&#xff0c;金价目前交投在1917美元附近。美国强劲PMI数据令金价承压&#xff0c;在美国数据走强和美联储发出鹰…
阅读更多...
Git 备忘单

Git 备忘单

Git 是一个去中心化的版本管理软件。通过这个备忘单&#xff0c;您将可以快速访问最常见的 git 命令。 配置 设置全局配置 git config --global user.name "[name]" git config --global user.email "[email]"开始使用 创建 git 存储库 git init克隆现…
阅读更多...
Java面试题：线程的run()和start()有什么区别？

Java面试题：线程的run()和start()有什么区别？

线程的 run() 方法和 start() 方法是 Java 多线程中的两个重 要方法。 1. run() 方法是线程的执行体&#xff0c;线程启动后会执行 run() 方法中的代码&#xff0c;当 run() 方法执行完毕后&#xff0c;线程便终止了。 2. start() 方法用于启动一个新线程&#xff0c;它会…
阅读更多...
【linux字符设备驱动-01】创建一个字符设备驱动

【linux字符设备驱动-01】创建一个字符设备驱动

目录 一、创建字符设备1、申请设备号方法一方法二 2、创建类方法一方法二 3、创建设备 二、创建字符设备驱动1、初始化&#xff1a;cdev_init2、添加到内核&#xff1a;cdev_add 三、一个完整的字符设备驱动程序1、驱动源码2、测试demo 一、创建字符设备 1、申请设备号 方法一…
阅读更多...
腾讯汤道生：超千亿参数 超2万亿tokens 腾讯混元大模型向行业全面开放

腾讯汤道生：超千亿参数 超2万亿tokens 腾讯混元大模型向行业全面开放

9月7日&#xff0c;2023腾讯全球数字生态大会在深圳宝安举行。腾讯集团高级执行副总裁、云与智慧产业事业群CEO汤道生表示&#xff0c;腾讯将迈入“全面拥抱大模型”时代&#xff1a;“以大模型生成技术为核心&#xff0c;人工智能正在成为下一轮数字化发展的关键动力&#xff…
阅读更多...
stable diffusion实践操作-SD原理

stable diffusion实践操作-SD原理

系列文章目录 本文专门开一节写SD原理相关的内容&#xff0c;在看之前&#xff0c;可以同步关注&#xff1a; stable diffusion实践操作 文章目录 系列文章目录前言一、原理说明1.1、出图原理1.1.1 AI画画不是和人一样&#xff0c;从0开始&#xff0c;而是一个去噪点的过程&am…
阅读更多...
华为云云服务器评测｜详解 Nacos 安装部署

华为云云服务器评测｜详解 Nacos 安装部署

环境配置 服务器云耀云服务器L操作系统CentOS 7.9 64bit | 公共镜像JDK64 bit JDK 1.8MavenMaven 3.2.xnacos-server2.2.3 下载地址 官方githubRelease 2.2.3 (May 25th, 2023) alibaba/nacos GitHub百度网盘链接&#xff1a;https://pan.baidu.com/s/1K8UE6iJL2ZnosUY83b…
阅读更多...
金鸣识别名片识别模块 ，名片扫描仪的神仙“伴侣”

金鸣识别名片识别模块 ，名片扫描仪的神仙“伴侣”

名片扫描仪是现代办公中常见的设备&#xff0c;其作用是将纸质名片转换为电子格式并进行识别。在实现这一功能方面&#xff0c;使用自带OCR功能和金鸣识别两种方式均具有各自的优势。 一方面&#xff0c;自带OCR功能的名片扫描仪具有便捷性和即时性的优势。通过设备内置的OCR技…
阅读更多...
Qt Creator使用Clang Format方法

Qt Creator使用Clang Format方法

Qt Creator使用Clang Format 习惯性的想格式化代码&#xff0c;发现Qt Creator默认居然是没有代码格式化的&#xff0c;只有一个缩进。 Qt Creater中有个插件&#xff1a;beautifier&#xff0c;在"帮助->关于"插件中&#xff0c;开启“Beautifier”即可&#xf…
阅读更多...
CSS内联样式与外联样式

CSS内联样式与外联样式

第一种内联样式 通过HTML元素的style属性来设置CSS样式&#xff0c;语法如下: style"css属性:css属性值;"示例代码: <!DOCTYPE html> <html><head><title>01_第一种使用方式.html</title></head><body><!-- style&q…
阅读更多...
[PHP]empty一直返回true

[PHP]empty一直返回true

class Post {public function __get($key){return true;} }$post new Post(); var_dump(empty($post->a));// bool(true) PHP: 重载 - Manual 读取不可访问&#xff08;protected 或 private&#xff09;或不存在的属性的值时&#xff0c;__get() 会被调用。 当对不可访…
阅读更多...
开源库网格算法比较

开源库网格算法比较

对于Mesh&#xff0c;我们通常分为结构化网格和非结构化网格。理解很简单&#xff0c;除了四边形和六面体是结构化网格&#xff0c;其它都是非结构化网格 最近在学习网格算法&#xff0c;本人关心的主要是3D网格相关的算法&#xff0c;总结了一下主要包括&#xff1a;网格生成…
阅读更多...
删除单链表偶数节点

删除单链表偶数节点

本题要求实现两个函数&#xff0c;分别将读入的数据存储为单链表、将链表中偶数值的结点删除。链表结点定义如下&#xff1a; struct ListNode { int data; struct ListNode *next; }; 函数接口定义&#xff1a; struct ListNode *createlist(); struct ListNode *deleteeven( …
阅读更多...
Git的安装以及基础使用方法

Git的安装以及基础使用方法

Git是一种分布式版本控制系统&#xff0c;被广泛用于管理代码、文档和任何其他类型的数据。它允许开发者在团队中协作&#xff0c;并且在处理大型项目时可以保持代码的完整性。 这里写目录标题 一、安装和设置二、基本的Git命令三、分支和合并四、标签和远程仓库 一、安装和设置…
阅读更多...
最新文章

Copyright @ 2022~2023