位置: IT常识 - 正文

Swagger-的使用(详细教程)

编辑:rootadmin
Swagger-的使用(详细教程) 文章目录前言一、简介二、基本使用1. 导入相关依赖2. 编写配置文件2.1 配置基本信息2.2 配置接口信息2.3 配置分组信息3. 控制 Swagger 的开启4. 常用注解使用@ApiModel@ApiModelProperty@ApiOperation@ApiParam5. 接口调用三、进阶使用1. 添加请求头四、项目下载前言

推荐整理分享Swagger-的使用(详细教程),希望有所帮助,仅作参考,欢迎阅读内容。

文章相关热门搜索词:,内容如对您有帮助,希望把文章链接给更多的朋友!

作为后端开放人员,最烦的事就是自己写接口文档和别人没有写接口文档,不管是前端还是后端开发,多多少少都会被接口文档所折磨,前端会抱怨后端没有及时更新接口文档,而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题,以一套标准的规范定义接口以及相关的信息,就能做到生成各种格式的接口文档,生成多种语言和客户端和服务端的代码,以及在线接口调试页面等等。只需要更新 Swagger 描述文件,就能自动生成接口文档,做到前端、后端联调接口文档的及时性和便利性。

一、简介

官网:https://swagger.io/

Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。二、基本使用1. 导入相关依赖

通过在项目中引入 Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。

<!-- 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. 编写配置文件

在配置文件 config 目录下,添加 swagger 的配置文件 SwaggerConfig.java

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

这个时候 Swagger 已经算是整合到项目之中了,可以启动下服务,输入:http://localhost:8080/swagger-ui.html# (这里我的项目端口是 8868 ,项目路径是 /mike,所以我打开的文档地址为 http://localhost:8868/mike/swagger-ui.html# )即可查看 swagger 文档。

可以看到 Swagger 文档中大概有这四类信息

组基本信息接口信息实体类信息2.1 配置基本信息

Swagger 有自己的实例 Docket,如果我们想要自定义基本信息,可以使用 docket 来配置 swagger 的基本信息,基本信息的设置在 ApiInfo 这个对象中。

Swagger 默认的基本信息展示

ApiInfo 中默认的基本设置

title:Api Documentationdescription:Api Documentationversion:1.0termsOfServiceUrl:urn:toscontact:无license:Apache 2.0licenseUrl:http://www.apache.org/licenses/LICENSE-2.0

SwaggerConfig.java 配置文件添加以下内容:

@Bean public Docket docket() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) // 配置基本信息 .apiInfo(apiInfo()) ; } // 基本信息设置 private ApiInfo apiInfo() { Contact contact = new Contact( "米大傻", // 作者姓名 "https://blog.csdn.net/xhmico?type=blog", // 作者网址 "777777777@163.com"); // 作者邮箱 return new ApiInfoBuilder() .title("多加辣-接口文档") // 标题 .description("众里寻他千百度,慕然回首那人却在灯火阑珊处") // 描述 .termsOfServiceUrl("https://www.baidu.com") // 跳转连接 .version("1.0") // 版本 .license("Swagger-的使用(详细教程)") .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535") .contact(contact) .build(); }

重启服务,打开 Swagger 文档,基本信息改变如下所示:

2.2 配置接口信息

默认情况下,Swagger 是会展示所有的接口信息的,包括最基础的 basic-error 相关的接口

有时候我们希望不要展示 basic-error-controller 相关的接口,或者是说这想要显示某些接口,比如说:user-controller 下的接口,由该怎么去实现呢?这个时候就需要设置 扫描接口

@Bean public Docket docket() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors //.any() // 扫描全部的接口,默认 //.none() // 全部不扫描 .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口,最为常用 //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口 //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口 ) .paths(PathSelectors .any() // 满足条件的路径,该断言总为true //.none() // 不满足条件的路径,该断言总为false(可用于生成环境屏蔽 swagger) //.ant("/user/**") // 满足字符串表达式路径 //.regex("") // 符合正则的路径 ) .build(); }

可根据自己的需求去设置对应的配置,这里我就不再一一赘述了,以上是我所设置的配置,重启服务,打开 Swagger 文档,接口信息改变如下所示:

可以看到之前 basic-error-controller 相关的接口已经没有了

2.3 配置分组信息

Swagger 默认只有一个 default 分组选项,如果没有设置,所有的接口都会显示在 default `分组下,如果功能模块和接口数量一多,就会显得比较凌乱,不方便查找和使用。

swagger 文档中组名默认是 default,可通过 .groupName(String )

@Bean public Docket docket() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改组名为 "mike" ; }

修改后: 如果需要配置多个组的话,就需要配置多个 docket() 方法,这里我就简单写两组,代码如下:

/** * 展示 controller 包下所有的接口 */ @Bean public Docket docket1() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改组名为 "mike" // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口,最为常用 ) .paths(PathSelectors .any() // 满足条件的路径,该断言总为true ) .build(); } /** * 展示路径为 /error 的所有接口(基础接口) */ @Bean public Docket docket2() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("yank") // 修改组名为 "yank" // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors .any() // 扫描全部的接口,默认 ) .paths(PathSelectors .ant("/error") // 满足字符串表达式路径 ) .build(); }

重启服务,打开 Swagger 文档,接口信息改变如下所示:

组名为 mike 的文档中只有 user-controller 相关的接口信息

组名为 yank 的文档中只有 basic-error-controller 相关的接口信息

3. 控制 Swagger 的开启

在开发或者测试环境下,我们开启 swagger 会方便前端和后端的交互,但是如果在生产环境下也开启 swagger 的话,是会将接口暴露出去的,有极大风险,如何让 swagger 根据不同的环境来决定是否开启?

这里我准备了四个项目的配置文件,dev、test、pro 三个环境的配置文件仅是端口上的不同

application.yml -------------------------- 全局配置文件application-dev.yml -------------------- 开发环境配置文件application-test.yml -------------------- 测试环境配置文件application-pro.yml -------------------- 生产环境配置文件Swagger-的使用(详细教程)

application.yml 内容如下,用于指定选择的环境:

spring: profiles: active: dev

可以通过代码判断此时是在什么环境:dev、test、pro,如果是在 pro 生产环境,则关闭 swagger。

/** * swagger 配置 * @param environment 环境 */ @Bean public Docket docket(Environment environment) { // 设置环境范围 Profiles profiles = Profiles.of("dev","test"); // 如果在该环境返回内则返回:true,反之返回 false boolean flag = environment.acceptsProfiles(profiles); // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .enable(flag) // 是否开启 swagger:true -> 开启,false -> 关闭 ; }

在 application.yml 全局配置文件中环境指向 dev 时,是可以打开 swagger 的

如果我将 application.yml 全局配置文件中环境指向 pro 时,就不能打开 swagger 了,提示 Could not render e, see the console

4. 常用注解使用

之前有说 Swagger 会将接口请求或者相应的实体类信息展示在 Models 下的,比如我 UserController.java 下有一个接口如下所示:

@PostMapping(value = "/query-user-info") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); }

它的请求体是 IdReq,响应是 ResponseBean,Models 展示这两个实体类信息如下:

前端可通过看这个 Models 知道后端定义实体类的信息。

@ApiModel

该注解是作用于类上面的,是用来描述类的一些基本信息的。

相关属性:

value:提供类的一个备用名,如果不设置,默认情况下将使用 class 类的名称description:对于类,提供一个详细的描述信息parent:这个属性用于描述的是类的一些父类信息discriminator:这个属性解释起来比较麻烦,因为这个类主要体现在断言当中subTypes:可以通过这个属性,指定我们想要使用的子类

譬如:这个为给 IdReq 这个类添加该注解

@Data@NoArgsConstructor@AllArgsConstructor@ApiModel(value = "Id请求体")public class IdReq { private String id;}

可以看到这里的名字从 IdReq 变成 Id请求体 了

@ApiModelProperty

它的作用是添加和操作属性模块的数据。

该注解的使用详情可参见博客:@ApiModelProperty注解的用法

这里我还是以 IdReq 类为例,为该类的属性添加说明

@Data@NoArgsConstructor@AllArgsConstructor@ApiModel(value = "Id请求体")public class IdReq { @ApiModelProperty("主键id") private String id;}

可以看到这里对该字段有一个备注说明。

@ApiOperation

该注解用来对某个方法/接口进行描述

该注解的使用详情可参见博客:Swagger @ApiOperation 注解详解

这里我以 UserController 下的接口为例:

@PostMapping(value = "/query-user-info") @ApiOperation(value = "根据id查询用户详情") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); }

可以看见该接口就多了对其的描述信息。

@ApiParam

该注解使用在方法上或者参数上,字段说明,表示对参数的添加元数据(说明或者是否必填等)

相关属性:

name:参数名value:参数说明required:是否必填

这里我以 UserController 下的接口为例:

@PostMapping(value = "/query-user-infos") @ApiOperation(value = "条件查询用户信息") public ResponseBean queryUserInfos( // name 用户名称 不必填 @ApiParam(value = "用户名称", required = false) @RequestParam(required = false) String name, // gender 用户性别 必填 @ApiParam(value = "用户性别", required = true) @RequestParam(required = true) GenderEnum gender ) { return ResponseBean.success(userService.queryUserInfos(name,gender)); }

这里会展示请求参数的备注信息,以及是否必填等。

5. 接口调用

使用 swagger 除了让前后端交互变得方便,也让接口的请求变得简单,只需要填写好请求所需要的参数信息,便可直接发起请求。

比如说接口 /user/query-user-info

点击 Try it out

设置好请求所需的参数,点击 Execute 执行

就能看到接口响应的结果了

接口 /user/query-user-infos 也差不多

三、进阶使用1. 添加请求头

有时候我们的接口是需要获取请求头信息的,这样的话就还需要在 swagger 配置中添加请求头的配置。

@Bean public 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 = "/get-token") @ApiOperation(value = "获取请求头中的token信息") public void getToken( @RequestHeader(value = "token",required = false) 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); } }

可以看到这个接口已经可以去设置请求头了,调用接口

后端也能获取到。

四、项目下载

以下是我这个项目所编写的代码 链接:百度网盘 提取码:na2o

相关博客: SpringBoot - 快速搭建

本文链接地址:https://www.jiuchutong.com/zhishi/298953.html 转载请保留说明!

上一篇:UNet - unet网络(program status)

下一篇:FCN全卷积网络理解及代码实现(来自pytorch官方实现)(全卷积网络fcn详解)

  • 荣耀v30安兔兔跑分是多少(荣耀v30pro安兔兔ai才12万怎么回事)

    荣耀v30安兔兔跑分是多少(荣耀v30pro安兔兔ai才12万怎么回事)

  • 引用的账户当前已锁定且可能无法登录win10(引用的账户当前已锁定且可能无法登录 win7)

    引用的账户当前已锁定且可能无法登录win10(引用的账户当前已锁定且可能无法登录 win7)

  • 单元格纵向转横向怎么做(单元格横纵变换)

    单元格纵向转横向怎么做(单元格横纵变换)

  • 怎么办理大王卡呢(怎么办理大王卡19月租)

    怎么办理大王卡呢(怎么办理大王卡19月租)

  • 快手收货了怎么退货(快手收货怎么修改手机号码)

    快手收货了怎么退货(快手收货怎么修改手机号码)

  • 为什么找不到撤销退款(为什么找不到撤销退货退款申请)

    为什么找不到撤销退款(为什么找不到撤销退货退款申请)

  • nova3e和哪个手机壳通用(华为nova3e好还是3i好)

    nova3e和哪个手机壳通用(华为nova3e好还是3i好)

  • 淘宝星级标准(淘宝星级标准怎么看)

    淘宝星级标准(淘宝星级标准怎么看)

  • 计算机病毒可以使整个计算机瘫痪危害极大计算机病毒是(计算机病毒可以自我复制吗)

    计算机病毒可以使整个计算机瘫痪危害极大计算机病毒是(计算机病毒可以自我复制吗)

  • 爱国者充电宝充不进电(爱国者充电宝充一会就不充了)

    爱国者充电宝充不进电(爱国者充电宝充一会就不充了)

  • ipad air3有耳机孔吗(ipadair3有耳机插孔吗)

    ipad air3有耳机孔吗(ipadair3有耳机插孔吗)

  • 微型计算机存储器系统中的Cache是(微型计算机存储器的分类图)

    微型计算机存储器系统中的Cache是(微型计算机存储器的分类图)

  • 华为p40是不是双卡双待(华为p60与mate50对比哪个好)

    华为p40是不是双卡双待(华为p60与mate50对比哪个好)

  • b站闪卡有什么用(哔哩哔哩ar闪卡)

    b站闪卡有什么用(哔哩哔哩ar闪卡)

  • 升级ios13.3后怎么降级(升级ios 13)

    升级ios13.3后怎么降级(升级ios 13)

  • ps吸颜色快捷键(ps吸色填色快捷键)

    ps吸颜色快捷键(ps吸色填色快捷键)

  • iphone6p电池多少毫安(iphone6plus电池多大)

    iphone6p电池多少毫安(iphone6plus电池多大)

  • word表格行距怎么设置(word表格行间距怎么调整不了)

    word表格行距怎么设置(word表格行间距怎么调整不了)

  • 抖音如何设置不让合拍(抖音如何设置不把自己的好友推荐给别人)

    抖音如何设置不让合拍(抖音如何设置不把自己的好友推荐给别人)

  • 小米摄像头离线怎么办(小米摄像头离线怎么重新连接)

    小米摄像头离线怎么办(小米摄像头离线怎么重新连接)

  • 支付宝扫码骑共享单车怎么收费(支付宝扫码骑共享单车可以在蚂蚁森林产生能量)

    支付宝扫码骑共享单车怎么收费(支付宝扫码骑共享单车可以在蚂蚁森林产生能量)

  • xr无法打开applestore

    xr无法打开applestore

  • 耳机有声音麦不能说话(耳机有麦但是说不了话)

    耳机有声音麦不能说话(耳机有麦但是说不了话)

  • win10如何自定义浏览器 win10系统设置默认浏览器方法(win10如何自定义鼠标指针)

    win10如何自定义浏览器 win10系统设置默认浏览器方法(win10如何自定义鼠标指针)

  • vue3在运行时路由可以正常跳转,但是页面空白,刷新页面恢复正常[已解决](vue程序运行过程)

    vue3在运行时路由可以正常跳转,但是页面空白,刷新页面恢复正常[已解决](vue程序运行过程)

  • 土地使用税计入税金及附加吗
  • 政府征用土地补偿标准2021年
  • 增值税分录及账务处理如何做?
  • 以固定资产投资的会计处理
  • 增值税专用发票怎么开
  • 资产减值损失影响利润吗
  • 深圳增值税普通发票查询真伪
  • 怎么强调各个分公司之间无直接联系
  • 劳保如何入账
  • 房地产企业被收购报表处理
  • 正版手写
  • 税务机关如何防范关联企业涉税风险问题
  • 公司化验室领用丙材料3000元
  • 税务退进项税会计处理
  • 预付款什么时候确认收入
  • 装修工程分期开票分期付款如何作账?
  • 税务开专票遇到四舍五入
  • 计提税金与缴纳有差额
  • 企业发生的装修费可以几年摊销
  • 小规模纳税人税收优惠政策
  • 货物已到发票未到怎么做账
  • 研发费用税点是什么意思
  • 煤炭企业税收政策
  • 开票满500万一定会升一般纳税人吗
  • 对方公司已注销,我公司应付款怎样支付
  • 哪些发票冲抵备用金
  • 计提生产设备折旧费计入什么科目
  • 劳务报酬的个税计算方法
  • windows7的笔记本有哪些
  • 小规模纳税人免增值税的账务处理
  • 一年内的待摊费用可以一次性进入成本吗
  • 行政事业单位捐款支出怎么记账
  • 如何防止电子发票重复报销
  • 本单位生产的水泥属于
  • 图森在哪
  • 监事 兼职
  • 数据库锁面试题
  • opencv图像处理入门与实践pdf
  • 取得专票怎么做账
  • 现金股利算负债吗
  • 同业代付业务会计核算
  • mongodb部署安装
  • 织梦怎么导入数据库
  • sqldbmon
  • sql server 2008数据库密码忘记
  • mysql 虚拟机
  • 个人所得税10月份申报期
  • 会计专业技术资格初级是什么职称
  • 职工报销的医药费是什么
  • 小微企业流转税优惠政策
  • 城镇土地使用税减免税政策
  • 捐赠支出入账
  • 企业员工福利费可以做什么
  • 结转已到期未兑现的商业承兑汇票会计分录
  • 股东分红入什么科目利润分配~应付利润
  • 资产减值损失会计处理
  • 调整去年管理费用怎么做分录
  • 公司账户可以转账到信用卡吗
  • 建总账的注意事项
  • sql server 文件
  • ubuntu安装软件没反应
  • 分区时把磁盘格式化了,如何恢复
  • 苹果系统怎么更新
  • vmstat命令
  • win10打
  • Ver、Vol、Ctty命令的使用教程
  • js计算时间差毫秒
  • jquery 延迟执行方法
  • jquery滚动到底部
  • css网站布局实录
  • 安卓手机本地
  • 详解使用Visual Studio Code对Node.js进行断点调试
  • javascript下拉列表怎么做
  • java script教程
  • jquery动态添加和删除div
  • 新疆税务局电子
  • 运输公司抵扣
  • 金融机构不包括
  • 江苏国税局官网登录
  • 郑州广电地址
  • 免责声明:网站部分图片文字素材来源于网络,如有侵权,请及时告知,我们会第一时间删除,谢谢! 邮箱:opceo@qq.com

    鄂ICP备2023003026号

    网站地图: 企业信息 工商信息 财税知识 网络常识 编程技术

    友情链接: 武汉网站建设