大型医疗挂号微服务“马上好医”医疗项目(5)Swagger的使用
Swagger的简单介绍
Swagger 是一个 RESTful 接口文档的规范和工具集,它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中,接口文档是非常重要的一环,它不仅方便开发者查看和理解接口的功能和参数,还能帮助前后端开发协同工作,提高开发效率。在 Spring Boot 中,我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口,然后根据这些注解自动生成接口文档。
同类型的产品
ApiDoc:
ApiDoc定位: ApiDoc=Postman+Swagger+mock+Jmeter,是一款集 API设计,接口文档管理、代码生成、API 调试、API mock,API 自动化为一体的接口一站式协作平台。
也就是说,它比 swagger 的的功能要更加广泛和齐全,不仅通过可视化界面设计接口生成接口文档和项目代码,
还打通了接口数据的协作流程,一套接口数据,设计出来可以给前端、测试使用,减少了再不同系统间切换、导入导出数据、更新维护的麻烦。
缺点:太繁琐,因为支持了太多的功能,并且也不符合注解式开发的规范,需要写大量的文档类东西。
Swagger的简单上手:
依赖:
<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>
配置:
Swagger是通过配置类的方式来添加配置的
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}
}
注解:
- @Api:用于描述接口的类或接口
- @ApiOperation:用于描述接口的方法
- @ApiParam:用于描述接口的参数
- @ApiModel:用于描述数据模型
- @ApiModelProperty:用于描述数据模型的属性
- @ApiImplicitParams:方法参数的说明
- @ApiImplicitParam:用于指定单个参数的说明
- @ApiResponses:方法返回值的说明
- @ApiResponse:用于指定单个参数的说明
注解属性:
- value:url的路径值
- tags :如果设置这个值、value的值会被覆盖
- description:对api资源的描述
- basePath:基本路径
- position:如果配置多个Api 想改变显示的顺序位置
- produces :“application/json, application/xml”
- consumes:“application/json, application/xml”
- protocols : http, https, ws, wss.
- authorizations: 高级特性认证时配置
- hidden :配置为true ,将在文档中隐藏
查看接口文档
启动 Spring Boot 应用后,我们可以在浏览器中访问http://localhost:8080/swagger-ui.html来查看接口文档。在 Swagger UI 页面中,我们可以看到所有的接口信息,包括接口名称、请求方式、请求路径、请求参数、响应参数等。
Swagger的用法:
1、描述数据模型
我们可以使用 @ApiModel 和 @ApiModelProperty 注解来描述数据模型和属性。例如,我们可以编写一个 User 类,并在类上使用 @ApiModel 和
@ApiModelProperty 注解来描述该数据模型:@ApiModel(description = "用户信息")
public class User {@ApiModelProperty(value = "用户 ID", example ="1") private Long id;@ApiModelProperty(value = "用户名", example = "张三")private String username;@ApiModelProperty(value = "密码", example = "123456")private String password;// 省略 getter 和 setter 方法
}
在上面的代码中,@ApiModel 表示该类是一个数据模型,@ApiModelProperty 表示该属性是数据模型的一个属性,value 属性表示属性的描述,example 属性表示属性的示例值。
2、描述枚举类型
我们可以使用 @ApiModel 和 @ApiModelProperty 注解来描述枚举类型。例如,我们可以编写一个 Gender 枚举类型,并在枚举值上使用 @ApiModelProperty 注解来描述该枚举值:
@ApiModel(description = "性别") public enum Gender {@ApiModelProperty(value = "男")
MALE,@ApiModelProperty(value = "女")
FEMALE;
}
在上面的代码中,@ApiModel 表示该枚举类型是一个描述性别的枚举类型,@ApiModelProperty 表示该枚举值是描述男性的枚举值或描述女性的枚举值。
3、描述响应参数
我们可以使用 @ApiResponses 和 @ApiResponse 注解来描述接口的响应参数。例如,我们可以编写一个 getUserById() 方法,并在方法上使用 @ApiResponses 和 @ApiResponse 注解来描述该方法的响应参数:
@GetMapping("/user/{id}")
@ApiOperation(value = "根据 ID 获取用户信息")
@ApiResponses({ @ApiResponse(code = 200, message = "请求成功", response = User.class),
@ApiResponse(code = 404, message = "用户不存在") })
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id)
{ // 根据 ID 查询用户信息
}
在上面的代码中,@ApiResponses 表示该方法的响应参数,@ApiResponse 表示该响应参数的描述,code 属性表示响应码,message 属性表示响应消息,response 属性表示响应的数据模型。
五、Swagger 的进阶使用
1、配置全局参数
我们可以在配置类中使用 globalOperationParameters() 方法来配置全局参数。例如,我们可以配置一个全局的 Authorization 参数,用于授权:
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().globalOperationParameters(Arrays.asList(new ParameterBuilder().name("Authorization").description("授权").modelRef(new ModelRef("string")).parameterType("header").required(false).build())).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}}
在上面的代码中,我们通过 globalOperationParameters() 方法来配置一个全局的 Authorization 参数,用于授权。
2、配置安全协议
我们可以在配置类中使用 securitySchemes() 方法来配置安全协议。例如,我们可以配置一个 Bearer Token 安全协议:
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(new ApiKey("Bearer", "Authorization", "header"))).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}}
在上面的代码中,我们通过 securitySchemes() 方法来配置一个 Bearer Token 安全协议。
3、配置安全上下文
我们可以在配置类中使用 securityContexts() 方法来配置安全上下文。例如,我们可以配置一个安全上下文,用于在 Swagger UI 中显示认证按钮:
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(new ApiKey("Bearer", "Authorization", "header"))).securityContexts(Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("Bearer", new AuthorizationScope[0]))).build())).apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("接口文档").description("接口文档").version("1.0.0").build();}}
在上面的代码中,我们通过 securityContexts() 方法来配置一个安全上下文,用于在 Swagger UI 中显示认证按钮。
4、配置忽略参数
在接口中,有些参数可能是敏感信息,我们不希望在接口文档中显示。我们可以使用 @ApiIgnore 注解来忽略这些参数。例如,我们可以在 User 类中使用 @ApiIgnore 注解来忽略密码参数:
@ApiModel(description = "用户信息")
public class User {@ApiModelProperty(value = "用户 ID", example = "1")private Long id;@ApiModelProperty(value = "用户名", example = "张三")private String username;@ApiModelProperty(hidden = true)@ApiIgnoreprivate String password;// 省略 getter 和 setter 方法
}
在上面的代码中,@ApiModelProperty(hidden = true) 表示该参数是隐藏的,@ApiIgnore 表示忽略该参数。
六、总结
通过集成 Swagger,我们可以方便地生成接口文档,使得前后端开发协同更加高效。在使用 Swagger 时,我们需要注意以下几点:
- 使用注解来描述接口信息,包括接口名称、请求方式、请求路径、请求参数、响应参数等;
- 在配置类中配置 Swagger,包括扫描的包路径、接口文档信息、全局参数、安全协议、安全上下文等;
- 描述数据模型、枚举类型、响应参数等信息,方便开发者查看和理解接口的功能和参数;
- 在需要时使用 @ApiIgnore 注解来忽略敏感参数的显示。
- 最后,需要注意的是,Swagger 只是一种规范和工具集,它并不能取代单元测试和集成测试等其他测试方式。在开发过程中,我们需要综合使用各种测试方式,保证软件的质量和稳定性。
相关文章:
大型医疗挂号微服务“马上好医”医疗项目(5)Swagger的使用
Swagger的简单介绍 Swagger 是一个 RESTful 接口文档的规范和工具集,它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中,接口文档是非常重要的一环,它不仅方便开发者查看和理解接口的功能和参数,还能帮助前后端开发协同…...
C语言从头学04——介绍占位符和输出格式
占位符、输出格式都是与 printf() 相关的,当然其它函数也有用到占位符的。这里先介绍它们在 printf() 的使用。 一、先介绍占位符,所谓“占位符”通俗讲就是先占个位置,后边再找具体值(参数)代入进行显示的一种方法。先用一个例子说明…...
写爬虫代码抓取Asterank中小行星数据
2024年5月4日 问题来源 解决方案 回顾2023年7月14日自己写的爬虫代码 import requests import re import pandas as pd texts[] def getData(page):#每页评论的网址urlhttps://item.jd.com/51963318622.html#comment#添加headers,伪装成浏览器headers{User-Agent:…...
leetCode81. 搜索旋转排序数组 II
leetCode81. 搜索旋转排序数组 II 题目思路 可以二分后的具体思路见我的上篇博客 搜索旋转排序数组 代码 class Solution { public:bool search(vector<int>& nums, int target) {if(nums.empty()) return false;int R nums.size() - 1;while(R > 0 &&…...
在Ubuntu上怎么查看安装了哪些包?
2024年5月3日,周五晚上 在Ubuntu上,你可以使用以下命令来查看系统中已安装的包: 使用dpkg命令:dpkg --list这个命令将列出系统中所有已安装的软件包,包括名称、版本号和描述等信息。你可以使用 grep 命令来过滤结果&a…...
Navicat连接远程数据库时,隔一段时间不操作出现的卡顿问题
使用 Navicat 连接服务器上的数据库时,如果隔一段时间没有使用,再次点击就会出现卡顿的问题。 如:隔一段时间再查询完数据会出现: 2013 - Lost connection to MySQL server at waiting for initial communication packet, syste…...
修改页签标题 + 页签图表
修改图标 在App.vue下的created()里或者路由守卫中输入 var link document.querySelector("link[rel*icon]") || document.createElement("link"); link.type "image/x-icon"; link.rel "shortcut icon"; link.href require(l…...
QT---day5,通信
1、思维导图 2、TCp 服务器 #ifndef MYWIDGET_H #define MYWIDGET_H #include <QWidget> #include <QTcpServer> #include <QList> #include <QTcpSocket> #include <QMessageBox> #include <QDebug> #include <QTcpServer> QT_B…...
设计模式: 工厂模式
工厂模式(Factory Pattern)是 Java 中最常用的设计模式之一,这种类型的设计模式属于创建型模式,它提供了一种创建对象的最佳方式。 工厂模式提供了一种创建对象的方式,而无需指定要创建的具体类。 工厂模式属于创建型…...
Java 多线程补充
线程池 Java线程池是一种能够有效管理线程资源的机制,它可以显著提高应用性能并降低资源消耗。 线程池的主要优点包括: 资源利用高效:通过重用已存在的线程,减少了频繁创建和销毁线程带来的系统开销。响应速度提升:…...
【Java基础】Maven继承
1. 前言 Maven 在设计时,借鉴了 Java 面向对象中的继承思想,提出了 POM 继承思想。 2. Maven继承 当一个项目包含多个模块时,可以在该项目中再创建一个父模块,并在其 POM 中声明依赖,其他模块的 POM 可通过继承父模…...
java技术总结
1.java基本数据类型? byte 1,short 2 ,int 4,long 8 ,float 4,double 8,boolean 1,char 2 2.java为什么要有包装类型? 前 6 个类派生于公共的超类 Number,而 Character 和 Boolean 是 Object 的直接子类。 被 final 修饰, Java 内置的包装类是无法被继承的。 包装…...
C# WinForm —— 12 ListBox绑定数据
ListBox加载大量数据时,避免窗体闪烁的方法: 在加载语句的前后分别加上 BeginUpdate()方法 和 EndUpdate()方法 指定一个集合为绑定的数据源 1. 首先,右键项目,添加类 2. 在新建的类文件中添加属性值信息 3. 构建初始化的对象…...
自动驾驶主流芯片及平台架构(二)特斯拉自动驾驶芯片平台介绍
早期 对外采购mobileye EyeQ3 芯片摄像头半集成方案,主要是为了满足快速量产需求,且受制于研发资金不足限制; 中期 采用高算力NVIDIA 芯片平台其他摄像头供应商的特斯拉内部集成方案,mobileye开发节奏无法紧跟特斯拉需求ÿ…...
powershell@管道符过滤的顺序问题@powershell管道符如何工作
文章目录 select 和 where谁先执行powershell管道符stop-service 为例查看文档中的典型参数介绍stop-process为例介绍管道符传参是怎么工作的Id参数InputObject 参数Name参数额外的试验反面例子应用:get-process 和stop-process配合 select 和 where谁先执行 在执行筛选时&…...
SMI接口
目录 SMI 接口帧格式读时序写时序 IP 设计IP 例化界面IP 接口IP 验证 SMI 接口 SMI(Serial Management Interface)串行管理接口,也被称作 MII 管理接口(MII Management Interface),包括 MDC 和 MDIO 两条信…...
【C++】转换构造函数和类型转换函数
目录 转换构造函数转换构造函数调用 类型转换函数类型转换函数定义形式应用 转换构造函数 转换构造函数就是一种构造函数,将一个其他类型的数据转换成一个类的对象的构造函数。 类型->类对象 转换构造函数调用 (1)显式强制类型转换&…...
全栈开发之路——前端篇(5)组件间通讯和接口等知识补充
全栈开发一条龙——前端篇 第一篇:框架确定、ide设置与项目创建 第二篇:介绍项目文件意义、组件结构与导入以及setup的引入。 第三篇:setup语法,设置响应式数据。 第四篇:数据绑定、计算属性和watch监视 辅助文档&…...
4.【Orangepi Zero2】Linux定时器(signal、setitimer),软件PWM驱动舵机(SG90)
Linux定时器(signal、setitimer),软件PWM驱动舵机(SG90) signalsetitimer示例 软件PWM驱动舵机(SG90) signal 详情请看Linux 3.进程间通信(shmget shmat shmdt shmctl 共享内存、si…...
K8S哲学 - 资源调度 HPA (horizontal pod autoScaler-sync-period)
kubectl exec: kubectl exec -it pod-name -c container-name -- /bin/sh kubectl run 通过一个 deployment来 演示 apiVersion: apps/v1 kind: Deployment metadata:name: deploylabels: app: deploy spec: replicas: 1selector: matchLabels:app: deploy-podt…...
web vue 项目 Docker化部署
Web 项目 Docker 化部署详细教程 目录 Web 项目 Docker 化部署概述Dockerfile 详解 构建阶段生产阶段 构建和运行 Docker 镜像 1. Web 项目 Docker 化部署概述 Docker 化部署的主要步骤分为以下几个阶段: 构建阶段(Build Stage):…...
Linux 文件类型,目录与路径,文件与目录管理
文件类型 后面的字符表示文件类型标志 普通文件:-(纯文本文件,二进制文件,数据格式文件) 如文本文件、图片、程序文件等。 目录文件:d(directory) 用来存放其他文件或子目录。 设备…...
【人工智能】神经网络的优化器optimizer(二):Adagrad自适应学习率优化器
一.自适应梯度算法Adagrad概述 Adagrad(Adaptive Gradient Algorithm)是一种自适应学习率的优化算法,由Duchi等人在2011年提出。其核心思想是针对不同参数自动调整学习率,适合处理稀疏数据和不同参数梯度差异较大的场景。Adagrad通…...
SciencePlots——绘制论文中的图片
文章目录 安装一、风格二、1 资源 安装 # 安装最新版 pip install githttps://github.com/garrettj403/SciencePlots.git# 安装稳定版 pip install SciencePlots一、风格 简单好用的深度学习论文绘图专用工具包–Science Plot 二、 1 资源 论文绘图神器来了:一行…...
DockerHub与私有镜像仓库在容器化中的应用与管理
哈喽,大家好,我是左手python! Docker Hub的应用与管理 Docker Hub的基本概念与使用方法 Docker Hub是Docker官方提供的一个公共镜像仓库,用户可以在其中找到各种操作系统、软件和应用的镜像。开发者可以通过Docker Hub轻松获取所…...
Cesium1.95中高性能加载1500个点
一、基本方式: 图标使用.png比.svg性能要好 <template><div id"cesiumContainer"></div><div class"toolbar"><button id"resetButton">重新生成点</button><span id"countDisplay&qu…...
visual studio 2022更改主题为深色
visual studio 2022更改主题为深色 点击visual studio 上方的 工具-> 选项 在选项窗口中,选择 环境 -> 常规 ,将其中的颜色主题改成深色 点击确定,更改完成...
iPhone密码忘记了办?iPhoneUnlocker,iPhone解锁工具Aiseesoft iPhone Unlocker 高级注册版分享
平时用 iPhone 的时候,难免会碰到解锁的麻烦事。比如密码忘了、人脸识别 / 指纹识别突然不灵,或者买了二手 iPhone 却被原来的 iCloud 账号锁住,这时候就需要靠谱的解锁工具来帮忙了。Aiseesoft iPhone Unlocker 就是专门解决这些问题的软件&…...
渲染学进阶内容——模型
最近在写模组的时候发现渲染器里面离不开模型的定义,在渲染的第二篇文章中简单的讲解了一下关于模型部分的内容,其实不管是方块还是方块实体,都离不开模型的内容 🧱 一、CubeListBuilder 功能解析 CubeListBuilder 是 Minecraft Java 版模型系统的核心构建器,用于动态创…...
【AI学习】三、AI算法中的向量
在人工智能(AI)算法中,向量(Vector)是一种将现实世界中的数据(如图像、文本、音频等)转化为计算机可处理的数值型特征表示的工具。它是连接人类认知(如语义、视觉特征)与…...
