Swagger笔记（狂神）

2024-03-27 18:58
文章标签 笔记 swagger 狂神

本文主要是介绍Swagger笔记（狂神），希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

Swagger

视频教程来自狂神说：https://space.bilibili.com/95256449

笔记来自：https://blog.csdn.net/weixin_44635198/article/details/107721418

  • 了解Swagger的概念及作用
  • 了解前后端分离
  • 在springboot中集成swagger

1、Swagger简介

前后端分离

Vue+SpringBoot

后端时代：前端只用管理静态页面；html==>后端。模板引擎JSP=>后端才是主力

前后端分离时代

Vue+SpringBoot

后端时代：前端只用管理静态页面；html==>后端。模板引擎JSP=>后端才是主力

前后端分离时代

  • 前端 -> 前端控制层、视图层

  • 伪造后端数据，json。已经存在了，不需要后端，前端工程队依旧能够跑起来

  • 后端 -> 后端控制层、服务层、数据访问层

  • 前后端通过API进行交互

  • 前后端相对独立且松耦合

产生的问题

  • 前后端集成联调，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

  • 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险；
  • 早些年：指定word计划文档；
  • 前后端分离：
    • 前端测试后端接口：postman
    • 后端提供接口，需要实时更新最新的消息及改动

Swagger

  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行，在线测试API
  • 支持多种语言 （如：Java，PHP等）
  • 官网：https://swagger.io/

2、SpringBoot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包

  • Springfox-swagger2
  • springfox-swagger-ui

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

  1. 新建一个SpringBoot-web项目

  2. 添加Maven依赖（注意：2.9.2版本之前，之后的不行）

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

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

  2. 要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}
  1. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

image-20200731132229265

3、配置Swagger

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

    bean其实就是实例对象.
    不过bean是spring中专属的概念（或者类似框架或容器）

    普通new出来的对象，叫对象。
    但是你把这个对象交给spring进行管理（通过component之类的），这样每次不用在代码里new了，它就变成bean了.

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2);
}
  1. 可以通过apiInfo()属性配置文档信息
//配置文档信息
private ApiInfo apiInfo() {Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");return new ApiInfo("Swagger学习", // 标题"学习演示如何配置Swagger", // 描述"v1.0", // 版本"http://terms.service.url/组织链接", // 组织链接contact, // 联系人信息"Apach 2.0 许可", // 许可"许可链接", // 许可连接new ArrayList<>()// 扩展);
}
  1. Docket 实例关联上 apiInfo()
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
  1. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

image-20200731161851136

4、配置扫描接口

  1. 构建Docket时通过select()方法配置怎么扫描接口。
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller")).build();
}
  1. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

image-20200731165837391

  1. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：
basePackage(final String basePackage) // 根据包路径扫描接口
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
  1. 除此之外，我们还可以配置接口扫描过滤：
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))// 配置如何通过path过滤,即这里只扫描请求以/ss开头的接口.paths(PathSelectors.ant("/ss/**")).build();
}
  1. 这里的可选值还有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

5、配置Swagger开关

  1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问.select().apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller")).paths(PathSelectors.ant("/ss/**")).build();
}

image-20200731190614381

  1. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？
@Bean
public Docket docket(Environment environment) {// 设置要显示swagger的环境Profiles of = Profiles.of("dev", "test");// 判断当前是否处于该环境// 通过 enable() 接收此参数判断是否要显示boolean b = environment.acceptsProfiles(of);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(b).select().apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")).paths(PathSelectors.ant("/ss/**")).build();
}
  1. 可以在项目中增加配置文件

  • dev测试环境

    server.port=8081

image-20200731193109826

项目运行结果

image-20200731193425090

  1. pro测试环境
server.port=8082

image-20200731194455510

项目运行结果

image-20200731194559290

6、配置API分组

  1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：
@Bean
public Docket docket(Environment environment) {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("狂神") // 配置分组// 省略配置....
}
  1. 重启项目查看分组

image-20200731195354714

  1. 如何配置多个分组？配置多个分组只需要配置多个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");
}
  1. 重启项目查看即可

image-20200731195543102

7、实体配置

  1. 新建一个实体类
//@Api("注释")
@ApiModel("用户实体")
public class User {@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}
}
  1. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
@RestController
public class HelloController {//   /error默认错误请求@GetMapping("/hello")public String hello() {return "hello";}//只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中@PostMapping("/user")public User user() {return new User();}
}
  1. 重启查看测试

image-20200731200413725

注：并不是因为**@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值**上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

  • @ApiModel为类添加注释

  • @ApiModelProperty为类属性添加注释

总结：

  • 我们可以通过Swagger给一些比较难理解的接口或者属性，增加注释信息
  • 接口文档实时更新
  • 可以在线测试

Swagger是一个优秀的工具，几乎所有大公司都有使用它

【注意点】：在正式发布的时候，关闭Swagger！！！

  • 出于安全考虑
  • 而且节省内存

8、常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

4hXRLq.png

我们也可以给请求的接口配置一些注释

  1. 在HelloController控制类中的接口添加api接口注释
@RestController
public class HelloController {......@ApiOperation("Hello控制接口")@GetMapping("/hello")public String hello2(@ApiParam("用户名") String username) {return "hello" + username;}@ApiOperation("get测试")@GetMapping("/get")public User hello2(@ApiParam("用户") User user) {return user;}
}

image-20200731201755001

  1. 进行try it out测试

image-20200731202958255

测试结果

image-20200731203034702

总结：

  1. 这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

  2. 相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

  3. Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

9、拓展：其他皮肤

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

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

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

image-20200731204929854

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

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.1</version>
</dependency>

image-20200731205550845

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency><groupId>com.github.caspar-chen</groupId><artifactId>swagger-ui-layer</artifactId><version>1.1.3</version>
</dependency>
  • 我这个测试没成功(Layui-ui)

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency><groupId>com.zyplayer</groupId><artifactId>swagger-mg-ui</artifactId><version>1.0.6</version>
</dependency>

image-20200731205723914

  • 我这个测试没成功(Layui-ui)

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency><groupId>com.zyplayer</groupId><artifactId>swagger-mg-ui</artifactId><version>1.0.6</version>
</dependency>

image-20200731205723914

这篇关于Swagger笔记（狂神）的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！


http://www.chinasem.cn/article/853077。

相关文章

SpringBoot3集成swagger文档的使用方法

SpringBoot3集成swagger文档的使用方法

《SpringBoot3集成swagger文档的使用方法》本文介绍了Swagger的诞生背景、主要功能以及如何在SpringBoot3中集成Swagger文档,Swagger可以帮助自动生成API文档... 目录一、前言1. API 文档自动生成2. 交互式 API 测试3. API 设计和开发协作二、使用
阅读更多...
【学习笔记】 陈强-机器学习-Python-Ch15 人工神经网络（1）sklearn

【学习笔记】 陈强-机器学习-Python-Ch15 人工神经网络（1）sklearn

系列文章目录 监督学习：参数方法 【学习笔记】 陈强-机器学习-Python-Ch4 线性回归 【学习笔记】 陈强-机器学习-Python-Ch5 逻辑回归 【课后题练习】 陈强-机器学习-Python-Ch5 逻辑回归（SAheart.csv） 【学习笔记】 陈强-机器学习-Python-Ch6 多项逻辑回归 【学习笔记 及 课后题练习】 陈强-机器学习-Python-Ch7 判别分析 【学
阅读更多...
系统架构师考试学习笔记第三篇——架构设计高级知识（20）通信系统架构设计理论与实践

系统架构师考试学习笔记第三篇——架构设计高级知识（20）通信系统架构设计理论与实践

本章知识考点：         第20课时主要学习通信系统架构设计的理论和工作中的实践。根据新版考试大纲,本课时知识点会涉及案例分析题(25分),而在历年考试中,案例题对该部分内容的考查并不多,虽在综合知识选择题目中经常考查,但分值也不高。本课时内容侧重于对知识点的记忆和理解,按照以往的出题规律,通信系统架构设计基础知识点多来源于教材内的基础网络设备、网络架构和教材外最新时事热点技术。本课时知识
阅读更多...
论文阅读笔记: Segment Anything

论文阅读笔记: Segment Anything

文章目录 Segment Anything摘要引言任务模型数据引擎数据集负责任的人工智能 Segment Anything Model图像编码器提示编码器mask解码器解决歧义损失和训练 Segment Anything 论文地址: https://arxiv.org/abs/2304.02643 代码地址:https://github.com/facebookresear
阅读更多...
数学建模笔记—— 非线性规划

数学建模笔记—— 非线性规划

数学建模笔记—— 非线性规划 非线性规划1. 模型原理1.1 非线性规划的标准型1.2 非线性规划求解的Matlab函数 2. 典型例题3. matlab代码求解3.1 例1 一个简单示例3.2 例2 选址问题1. 第一问 线性规划2. 第二问 非线性规划 非线性规划 非线性规划是一种求解目标函数或约束条件中有一个或几个非线性函数的最优化问题的方法。运筹学的一个重要分支。2
阅读更多...
【C++学习笔记 20】C++中的智能指针

【C++学习笔记 20】C++中的智能指针

智能指针的功能 在上一篇笔记提到了在栈和堆上创建变量的区别，使用new关键字创建变量时，需要搭配delete关键字销毁变量。而智能指针的作用就是调用new分配内存时，不必自己去调用delete，甚至不用调用new。 智能指针实际上就是对原始指针的包装。 unique_ptr 最简单的智能指针，是一种作用域指针，意思是当指针超出该作用域时，会自动调用delete。它名为unique的原因是这个
阅读更多...
查看提交历史 —— Git 学习笔记 11

查看提交历史 —— Git 学习笔记 11

查看提交历史 查看提交历史 不带任何选项的git log-p选项--stat 选项--pretty=oneline选项--pretty=format选项git log常用选项列表参考资料 在提交了若干更新，又或者克隆了某个项目之后，你也许想回顾下提交历史。 完成这个任务最简单而又有效的 工具是 git log 命令。 接下来的例子会用一个用于演示的 simplegit
阅读更多...
记录每次更新到仓库 —— Git 学习笔记 10

记录每次更新到仓库 —— Git 学习笔记 10

记录每次更新到仓库 文章目录 文件的状态三个区域检查当前文件状态跟踪新文件取消跟踪（un-tracking）文件重新跟踪（re-tracking）文件暂存已修改文件忽略某些文件查看已暂存和未暂存的修改提交更新跳过暂存区删除文件移动文件参考资料 咱们接着很多天以前的 取得Git仓库 这篇文章继续说。 文件的状态 不管是通过哪种方法，现在我们已经有了一个仓库，并从这个仓
阅读更多...
忽略某些文件 —— Git 学习笔记 05

忽略某些文件 —— Git 学习笔记 05

忽略某些文件 忽略某些文件 通过.gitignore文件其他规则源如何选择规则源参考资料 对于某些文件，我们不希望把它们纳入 Git 的管理，也不希望它们总出现在未跟踪文件列表。通常它们都是些自动生成的文件，比如日志文件、编译过程中创建的临时文件等。 通过.gitignore文件 假设我们要忽略 lib.a 文件，那我们可以在 lib.a 所在目录下创建一个名为 .gi
阅读更多...
取得 Git 仓库 —— Git 学习笔记 04

取得 Git 仓库 —— Git 学习笔记 04

取得 Git 仓库 —— Git 学习笔记 04 我认为， Git 的学习分为两大块：一是工作区、索引、本地版本库之间的交互；二是本地版本库和远程版本库之间的交互。第一块是基础，第二块是难点。 下面，我们就围绕着第一部分内容来学习，先不考虑远程仓库，只考虑本地仓库。 怎样取得项目的 Git 仓库？ 有两种取得 Git 项目仓库的方法。第一种是在本地创建一个新的仓库，第二种是把其他地方的某个
阅读更多...

Copyright China编程 23002807@qq.com

沪ICP备2023033072号-2