位置: 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详解)

  • 神舟笔记本t6-x5不能开机怎么办

    神舟笔记本t6-x5不能开机怎么办

  • 手机qq空间留言板在哪里(手机qq空间留言怎么删除)

    手机qq空间留言板在哪里(手机qq空间留言怎么删除)

  • 小牛电池充一夜可以吗(小牛电池充电过夜)

    小牛电池充一夜可以吗(小牛电池充电过夜)

  • 苹果8p怎么双击截屏(苹果8p怎么双击点亮)

    苹果8p怎么双击截屏(苹果8p怎么双击点亮)

  • WPS文件名冲突怎么改(wps文件名冲突怎么办)

    WPS文件名冲突怎么改(wps文件名冲突怎么办)

  • 微信聊天从列表中删除了能恢复吗(微信聊天从列表中删除后记录就没了)

    微信聊天从列表中删除了能恢复吗(微信聊天从列表中删除后记录就没了)

  • i11tws耳机是什么牌子(i11tws蓝牙耳机)

    i11tws耳机是什么牌子(i11tws蓝牙耳机)

  • 微信视频号是干嘛的(微信视频号运营)

    微信视频号是干嘛的(微信视频号运营)

  • 快手推送是什么意思(快手推送的内容是经常看的类型吗)

    快手推送是什么意思(快手推送的内容是经常看的类型吗)

  • emui10.1什么时候出(emui10.1什么时候发布)

    emui10.1什么时候出(emui10.1什么时候发布)

  • 微信不能解除限制怎么办(微信不能解除限制里面的钱怎么办)

    微信不能解除限制怎么办(微信不能解除限制里面的钱怎么办)

  • 手机照相机闪光灯怎么开(手机照相机闪光灯在哪)

    手机照相机闪光灯怎么开(手机照相机闪光灯在哪)

  • 6s可以用苹果七的耳机吗(6s可以用苹果七充电器吗)

    6s可以用苹果七的耳机吗(6s可以用苹果七充电器吗)

  • ipad外放没有声音(ipad外放没有声音维修要多少钱)

    ipad外放没有声音(ipad外放没有声音维修要多少钱)

  • 公交车可以扫码支付吗(乘车码公交二维码)

    公交车可以扫码支付吗(乘车码公交二维码)

  • word文档怎么加标注(word文档怎么加下划线,上面没有字)

    word文档怎么加标注(word文档怎么加下划线,上面没有字)

  • 拼多多怎么用支付宝付款(拼多多怎么用支付宝支付先用后付)

    拼多多怎么用支付宝付款(拼多多怎么用支付宝支付先用后付)

  • 华为畅享10有指纹解锁吗(华为畅享10有指纹支付吗)

    华为畅享10有指纹解锁吗(华为畅享10有指纹支付吗)

  • 万维网系统的主要用途(万维网系统的组成部分及具体的工作流程)

    万维网系统的主要用途(万维网系统的组成部分及具体的工作流程)

  • 苹果手机怎样取消软件的消息推送(苹果手机怎样取消自动续费的功能)

    苹果手机怎样取消软件的消息推送(苹果手机怎样取消自动续费的功能)

  • qq怎么看对方生日(qq怎么看对方生日信息)

    qq怎么看对方生日(qq怎么看对方生日信息)

  • 鸿蒙系统大文件夹怎么玩? 鸿蒙大文件翻页调整大小等操作的技巧(鸿蒙系统大文件夹怎么调节大小)

    鸿蒙系统大文件夹怎么玩? 鸿蒙大文件翻页调整大小等操作的技巧(鸿蒙系统大文件夹怎么调节大小)

  • elmentUI组建中el-date-picker实现限制时间范围精确到小时(elementui常用组件有哪些)

    elmentUI组建中el-date-picker实现限制时间范围精确到小时(elementui常用组件有哪些)

  • 资产的计税基础大于账面价值会形成可抵扣的暂时性差异
  • 暂估成本会计处理
  • 由第三方代付款开票给对方合规吗
  • 工程机械租赁增值税税率很多适用错误应该是9不是13
  • 劳务公司差额计税收到的代发工资怎么开票
  • 公司给离职员工多发工资怎么办
  • 个税专项扣除中途贷款改租房
  • 个税专项扣除如何迁移
  • 企业清算时
  • 税务系统勾了为什么还能认证?
  • 递延所得税资产和负债怎么理解
  • 企业所得税季度预缴纳税申报表
  • 公司经营困难情况说明怎么写
  • 专项资金需要交印花税吗
  • 商贸企业固定资产计提折旧吗
  • 限售股转让个人所得税
  • 收回公司代垫职工款项怎么做凭证?
  • 工程施工余额怎么处理
  • 金银制成的金银币及摆件是否征收消费税?
  • 工资薪金所得税前扣除项目标准
  • 应收账款少给货款怎么做分录?
  • php数组函数实现机选双色球
  • win10不关机设置方法
  • 短缺的材料算不算入账价值
  • 苹果macOS 11开发者预览版发布
  • php中ajax
  • php教程全集
  • h5调用海康摄像头
  • vue2+element-plus 密码校验及动态校验
  • 陆家嘴金融贸易区管委会主任
  • 自然语言处理属于人工智能的哪个领域
  • 二元运算例子
  • 借款利息收入开票
  • python迭代器iterator
  • 因质量原因退货和召回的产品,均应按照规定
  • 国外商贸公司
  • mongodb $nin
  • 应收保费核算什么业务
  • SQL Server 2005 DTS导入平面数据出现错误解决方案
  • 个体工商户要做账报税吗
  • 企业所得税季度申报表季度平均值
  • 建筑业跨区域预缴税款的计算
  • 个体工商户税务注销流程
  • 六税一费减免
  • 费用暂估是什么意思
  • 过路费发票抵扣政策
  • 发票未到货已入库会计分录 原材料
  • 公司聚餐做什么科目
  • 取得普通发票怎么做账
  • 企业单位为职工发放哪些福利
  • 广告发布费属于什么费用
  • 外汇申报国家代码表
  • 进项票取得晚了怎么抵扣
  • 行政单位负债类科目包括
  • 原股东决定
  • 维护费要交税吗
  • 并购成本计算公式
  • 新成立的公司需要年检吗
  • 施工企业应收账款周转率多少合适
  • 新开办企业如何建账
  • mysql解压版
  • windows mysql5.5升级5.7
  • linux几种安装方式
  • linux去掉指定字符
  • win7系统出现蓝屏怎么进去桌面
  • Android中的touch事件
  • js中的filter方法和map方法
  • 梦见擦窗户框
  • javascript的核心语言对象包括
  • 怎么使用vue和axios连接后端
  • jquery制作简单的网页
  • python处理文本文件代码优化
  • 如何用python编写一个程序
  • python中的zip()函数详解
  • 集资房税收问题
  • 湖北税务查询电话
  • 江苏电子税务局客服电话
  • 青岛的红叶什么时候红
  • 发票汇总表怎么计算
  • 遏制新增
  • 免责声明:网站部分图片文字素材来源于网络,如有侵权,请及时告知,我们会第一时间删除,谢谢! 邮箱:opceo@qq.com

    鄂ICP备2023003026号

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

    友情链接: 武汉网站建设