当前位置: 首页 > news >正文

【swagger2】开发api文档

文章目录

    • 一、swagger2 简介
      • 背景
      • Open API ???
      • swagger2的作用
      • swagger2常用工具组件:
    • 二、Springfox
    • 三、springBoot使用swagger2(简单示例)
    • 四、Swagger-UI使用
    • 五、配置文件
      • 1、配置类:给docket上下文配置api描述信息
      • 2、配置类:扫描包
      • 3、自定义注解设置不需要生成接口文档的方法
        • ▶@Target-描述当前的注解可以定义在什么资源上
        • ▶@Retention-当前注解在什么时候有效
        • ▶示例
      • 4、配置路径范围配置paths()
    • 六、Swagger2常用注解
      • 常用注解:
      • @Api
      • @ApiOperation
      • @ApiParam
      • @ApiImplicitParam-s
      • @ApiModel、@ApiModelProperty

一、swagger2 简介

官网:https://swagger.io/

背景

我们后端在编写项目的时候,往往都会在代码上加上注释,方便自己以后的修改和维护,和方便别人的理解。但是对对前后端分离的项目,前端人员写前端代码,后端人员编写后端的代码。这样的话当前端需要调用我们后端的接口的时候,就会来找我们询问参数以及请求的接口路径。如果每次都来问的话就会很繁琐。所以我们要讲我们自己编写的代码,生成一个api文档,里面描述了我们各种接口调用规则,我们只需要将这个api文档交给前端人员即可。前端人员就可以根据我们提供的文档获取到他们需要调用的接口路径以及参数信息。

Open API ???

Open API规范(OpenAPI Specification)以前叫做Swagger规范是RESTAPI的API描述格式。
Open API文件允许描述整个API,包括:

  • 每个访问地址的类型。POST 或GET。I
  • 每个操作的参数。包括输入输出参数。
  • ·认证方法。
  • 连接信息,声明,使用团队和其他信息。

Open API规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。

swagger2的作用

swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务
作用:

  • 接口的文档在线自动生成
  • 功能测试

用白话说就是:后端人员写完代码后,不想写开发文档,就嵌用api注解,代码启动,访问固定的路径: ip+端口+路径地址来访问代码。

swagger2常用工具组件:

1、Swagger Editor:基于浏览器编辑器,可以在里面编写Open API规范。类似
Markdown具有实时预览描述文件的功能。(还要自己写,需要会json或者yaml)
2、Swagger UI:将Open API规范呈现为交互式API文档。用可视化U展示描述文件。(注解)
3、Swagger Codegen:将OpenAPI规范生成为服务器存根和客户端库。通过Swagger
Codegen可以将描述文件生成html格式和 cwiki形式的接口文档;同时也可以生成多种
言语的客户端和服务端代码。
4、Swagger Hub:集成了上面所有项月的各个功能,你可以以项目和版本为单位,将你
的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,
需要注册账号,分免费版和收费版。

二、Springfox

使用Swagger时如果碰见版本更新或迭代时,只需要更改Swagger的描述文件即可。
但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件( yml或json )也是一种负担,就直接改代码,这样开发文档的作用就没意义了。

作用:
Spring-fox是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码即可,
而不需要跟随修改描述文件。

Spring-fox利用自身AOP 特性,把 Swagger集成进来,底层还是Swagger。但是使
用起来确方便很多。所以实际开发中使用springfox。
官网:http://springfox.github.io/springfox/
源码:https://github.com/springfox/springfox

三、springBoot使用swagger2(简单示例)

▶导入依赖:pom.xml,自己库里的其他版本都行

 <!--swagger2的依赖--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><!--视图逻辑swagger-ui--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version><scope>compile</scope></dependency>

▶先写一个controller,里面有三种请求方法,自定义、get、post

@RestController//方法中所有的返回值都相当于加了一个@ResponseBody
@RequestMapping("/user")
public class MyController {@PostMapping("/getUserById")//post请求public String post(Integer id){return "post:根据id获取User";}@GetMapping("/getUsers")//get请求public String get(){return "get:获取所有的User";}@RequestMapping("/req")//这种请求方式是不限制请求方式的,任意请求方式都可以访问public String req(String m){return "request!!!";}
}

▶在启动类上注解@EnableSwagger2

@EnableSwagger2
springfox提供的注解,代表swagger2相关技术开启,会扫描当前类所在包,及子包中所有的类型中的注解,

▶运行启动类,访问路径:http://localhost:8080/swagger-ui.html
在这里插入图片描述
在这里插入图片描述

访问swagger-ui.html后可以在页面中着到所有需要生成接口文档的控制器名称

  • basic-error-controller中:是springBoot内部的,关于错误提示的controller。
  • MyController:自己写的。其中有get和post的请求,还有一个没有限制请求方式的方法。
  • ……

四、Swagger-UI使用

【扫描我们编写的所有的控制器,扫描约束,显示在视图中(上面截图)】

@GetMapping("/get")
==这两个方法是等价的==
@RequestMapping(method = {RequestMethod. GET})

Swagger-UI:

  • 显示控制器
  • 显示控制器中的请求方法(路径地址的处理)、参数、名字等
  • 简单测试请求,以及返回的响应结果描述
    在这里插入图片描述

五、配置文件

上面提到过在视图中有些东西可以修改,与本项目的内容无关,就需要通过配置类来实现修改
在这里插入图片描述

1、配置类:给docket上下文配置api描述信息

@Configuration
public class SwaggerConfig1 {/*** 创建Docket类型的对象。并使用spring容器管理。* Docket是Swagger中的全局配置对象。* @return docket*/@Beanpublic Docket createRestApi() {Docket docket = new Docket(DocumentationType.SWAGGER_2);//API帮助文档的描述信息ApiInfo apiInfo = new ApiInfoBuilder().contact(             //配置swagger文档主体内容new Contact("简单示例Swagger的开发文档",   //是文档的发布者名称"http://www/xxxx",      //是文档发布者的网站地址。企业网站"admin@bjsxt.com")       //文档发布者的电子邮箱).title("swagger文档标题").description("swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,开发帮助文档").version("1.1").build();docket.apiInfo(apiInfo);return docket;}
}

文档运行路径:http://localhost:8080/swagger-ui.html,对比上张图,观察上下文配置api描述信息都是修改的文档的哪个地方。
在这里插入图片描述

2、配置类:扫描包

   docket.select()   		//获取Docket中的选择器。返回ApiSelectorBuilder。构建选择器的。如:扫描什么包的注解.apis(RequestHandlerSelectors.basePackage("com.wxy.springboot_swagger.controller"));  //规则,设定扫描哪个包(包含子包)

3、自定义注解设置不需要生成接口文档的方法

▶@Target-描述当前的注解可以定义在什么资源上

属性value定义具体的资源,常用:

  • ElementType.METHOD可以定义在方法上
  • EIementType.TYPE可以定义在类型上
  • ElementType.FIELD可以定义在属性上
  • ElementType.PARAMETER可以定义在方法参数上
  • ……

▶@Retention-当前注解在什么时候有效

属性value-定义具体的生效标记三个:

  • RetentionPolicy.RUNTIME-运行时有效(常用)
  • RetentionPolicy.SOURCE一源码中有效
  • RetentionPolicy.CLASS-字节码有效

▶示例

1.写一个自定义注解类

/*** @interface 代表当前是一个注解类*/
@Target(value = {ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotationSwagger {//自定义注解中的属性。相当于@MyAnnotationSwagger(value="")String value() default "";
}

2.自定义注解的使用:实现controller中“req()”方法不在文档视图中显示
要在controller中req()的方法上添加注解@MyAnnotationSwagger
在这里插入图片描述
在配置类中设置规则匹配器(内部是静态方法)

docket = docket.select()   //获取Docket中的选择器。返回ApiSelectorBuilder。构建选择器的。如:扫描什么包的注解//.apis(RequestHandlerSelectors.basePackage("com.wxy.springboot_swagger2.controller"))  //规则,设定扫描哪个包(包含子包).apis(Predicates.not(  //取反:false->true true->falseRequestHandlerSelectors.withMethodAnnotation(  //withMethodAnnotation:当方法上有注解时返回trueMyAnnotationSwagger.class))         //方法有什么注解的时候返回true).build();  //重新构建Docket对象

测试:只有get和post两个方法了
在这里插入图片描述
Predicates.and()
在这里插入图片描述

4、配置路径范围配置paths()

.paths(PathSelectors.regex("/swagger/.*") //使用正则表达式,约束生成API文档的路径地址。//控制器访问路径以swagger开头的。@RequestMapping("/swagger")
)

在这里插入图片描述

.paths(Predicates.or( //多个规则符合任意一个即可通过。PathSelectors.regex(pathRegex:"/swagger/.*"),PathSelectors.regex(pathRegex:"/swagger2/.*"),PathSelectors.regex(pathRegex:"/.*"))
)

六、Swagger2常用注解

常用注解:

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

  • @Api:修饰整个类,描述Controller的作用。
    • tags:给当前类型定义别名,可以有多个。定义几个别名,在ui视图中就显示几个控制器访问菜单。
    • description:定义描述
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:描述实体类型,用对象来接收参数
  • @ApiModelProperty:用对象接收参数时,描述对象的一个字段
  • @ApiImplicitParam:在方法上描述方法的一个请求参数
  • @ApiImplicitParams:多个请求参数
  • @ApiIgnore:忽略当前注解描述的方法或类型,不生成api帮助文档

@Api

@RestController
@RequestMapping("/user")
@Api(tags = {"MyController","Swagger测试控制器"},description = "测试API类型描述信息")
public class MyController {……
}

在这里插入图片描述

@ApiOperation

    @PostMapping("/getUserById")//post请求@ApiOperation(value = "post方法,执行新增操作", notes = "Swagger学习使用-处理POST请求的方法")public String post(Integer id){return "post:根据id获取User";}

在这里插入图片描述

@ApiParam

在这里插入图片描述
在这里插入图片描述

@ApiImplicitParam-s

@GetMapping("/test")
@ApiImplicitParam(name = "m", value = "m参数描述",required = false, paramType = "字符串",dataType = "明值对")
public String test(String m,String n){return "request!!!";
}

在这里插入图片描述

@ApiImplicitParams(value = {@ApiImplicitParam(name = "m", value = "m参数描述",required = false, paramType = "字符串",dataType = "明值对"),@ApiImplicitParam(name = "n", value = "n参数描述",required = true, paramType = "字符串",dataType = "明值对")})

@ApiModel、@ApiModelProperty

/*** ApiModel 描述一个实体类型。这个实体类型如果成为任何一个生成api帮助文档方法的* 返回值类型的时候,此注解被解析。*/
@ApiModel(value = "自定义实体类",description = "MyEntity存储用户数据")
public class MyEntity implements Serializable {@ApiModelProperty(value = "主键",name = "主键(id)",required = false,example = "1",hidden = false)private String id;@ApiModelProperty(value = "姓名",name = "姓名(name)",required = true,example = "张三",hidden = false)private String name;@ApiModelProperty(value = "密码",name = "密码(password)",required = true,example = "123456",hidden = false)private String password;public MyEntity(){}public String getId() {return id;}public void setId(String id) {this.id = id;}public String getName() {return name;}public void setName(String name) {this.name = name;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}@Overridepublic boolean equals(Object o) {if (this == o) return true;if (o == null || getClass() != o.getClass()) return false;MyEntity myEntity = (MyEntity) o;return Objects.equals(id, myEntity.id) && Objects.equals(name, myEntity.name) && Objects.equals(password, myEntity.password);}@Overridepublic int hashCode() {return Objects.hash(id, name, password);}
}

返回类型是实体类类型:

   @RequestMapping("/testEntity")public MyEntity testEntity(){return new MyEntity();}

在这里插入图片描述

相关文章:

【swagger2】开发api文档

文章目录一、swagger2 简介背景Open API ???swagger2的作用swagger2常用工具组件&#xff1a;二、Springfox三、springBoot使用swagger2&#xff08;简单示例&#xff09;四、Swagger-UI使用五、配置文件1、配置类&#xff1a;给docket上下文配置api描述信息2、配置类&#…...

Github 上如何提交 pull request

什么是复刻&#xff08;forking&#xff09;? 我们可以通过复刻操作将喜爱的仓库保存自己的Github账户中&#xff0c;以便独立地对其进行操作。 通过复刻&#xff0c;我们可以得到包含完整版本历史的目标仓库的实例&#xff0c;之后可以对复刻得到的仓库进行任意操作而不会影响…...

Redis面试知识

概述 Redis 是速度非常快的非关系型(NoSQL)内存键值数据库,可以存储键和五种不同类型的值之间的映射。 键的类型只能为字符串,值支持五种数据类型:字符串、列表、集合、散列表、有序集合。 Redis 支持很多特性,例如将内存中的数据持久化到硬盘中,使用复制来扩展读性能…...

Spring面试重点(四)——Spring事务

Spring事务 事务的方式 spring中使用事务有两种方式&#xff0c;一种是编程式事务&#xff0c;一种是声明式事务。编程式事务推荐使用TransactionTemplate&#xff0c;实现TransactionCallback接口&#xff0c;需要编码实现&#xff1b;声明式事务只需要在函数增加注解Transa…...

♡ — MySQL 存储引擎

MySQL 存储引擎架构 MySQL 存储引擎采用的是插件式架构&#xff0c;支持多种存储引擎&#xff0c;我们甚至可以为不同的数据库设置不同的存储引擎以适应不同场景的需要&#xff1b;存储引擎是基于表的&#xff0c;而不是数据库。 MyISAM 和 InnoDB 的区别 MySQL 5.5 之前&am…...

大数据技术架构(组件)34——Spark:Spark SQL--Optimize

2.2.3、Optimize2.2.3.1、SQL3.3.1.1、RB1、Join选择在Hadoop中&#xff0c;MR使用DistributedCache来实现mapJoin。即将小文件存放到DistributedCache中&#xff0c;然后分发到各个Task上&#xff0c;并加载到内存中&#xff0c;类似于Map结构&#xff0c;然后借助于Mapper的迭…...

Zookeeper实现分布式锁

文章目录ZK节点类型watch监听机制Zookeeper实现分布式锁锁原理创建锁的过程释放锁的过程ZK锁的种类代码实现Zookeeper是一个开源的分布式协调服务&#xff0c;是一个典型的分布式数据一致性解决方案。 分布式应用程序可以基于Zookeeper实现诸如数据发布/订阅&#xff0c;负载均…...

MFC 添加重新启动管理器支持

重启管理器是添加到 Visual Studio for Windows Vista 或更高版本操作系统的功能 如果发生意外关闭或重启&#xff0c;重新启动管理器将为你的应用程序添加支持。 重新启动管理器的行为取决于应用程序的类型。 如果你的应用程序是文档编辑器&#xff0c;则重新启动管理器让应用…...

一文带你深刻的进入Python,并且了解Python的优缺点

最近几年Python被吹的神乎其神&#xff0c;很多同学都不清楚Python到底能干什么&#xff1f;就盲目去学习Python,今天我就Python的应用领域来简单盘点一下&#xff0c;让想学习Python 的同学找对方向不迷茫。 2. Python 的特点 这里就谈谈自己的看法&#xff0c;首先 Python是…...

别具一格,原创唯美浪漫情人节表白专辑,(复制就可用)(html5,css3,svg)表白爱心代码(4)

别具一格,独此一家&#xff0c;原创唯美浪漫情人节表白专辑 不一样的惊喜哦~&#xff01;&#xff08;html5,css3,svg)表白爱心代码&#xff08;复制就可用&#xff09;&#xff08;4&#xff09; 目录 款式四&#xff1a;时光的记忆款 1、拷贝完整源代码 2、更新时光盒所…...

编译原理—翻译方案、属性栈代码

系列文章戳这里&#x1f447; 什么是上下文无关文法、最左推导和最右推导如何判断二义文法及消除文法二义性何时需要消除左递归什么是句柄、什么是自上而下、自下而上分析什么是LL(1)、LR(0)、LR(1)文法、LR分析表LR(0)、SLR(1)、LR(1)、LALR(1)文法之间的关系编译原理第三章习…...

链表

一、从尾到头打印链表题目&#xff1a;输入一个链表&#xff0c;按链表从尾到头的顺序返回一个ArrayList。解题思路&#xff1a;使用栈作为中转&#xff0c;可以实现倒置打印classSolution { public:vector<int> printListFromTailToHead(ListNode* head){//使用栈完成中…...

CSS 样式优先级

CSS 样式优先级决定了最终呈现在浏览器中的样式是哪一组样式&#xff0c;在多组样式中有冲突时&#xff0c;最终呈现在浏览器中的样式是具有最高优先级的样式。 CSS 样式优先级顺序如下&#xff1a; 内联样式 > 内部样式 > 外部样式 !important > 内联样式 > ID…...

SpingMVC获取请求参数

通过ServletAPI获取请求参数将HttpServletRequest作为控制器方法的形参&#xff0c;此时HttpServletRequest类型的参数表示封装了当前请求的请求报文的对象。html<form th:action"{/param/servletAPI}" method"post">用户名&#xff1a;<input ty…...

微搭使用笔记(二)微搭低代码平台介绍及基础使用

概述 官网地址&#xff1a; 官网 官方文档&#xff1a; 官方文档 FAQ: FAQ 腾讯云微搭低代码是一个高性能的低代码开发平台&#xff0c;用户可通过拖拽式开发&#xff0c;可视化配置构建 PC Web、H5 和小程序应用。支持打通企业内部数据&#xff0c;轻松实现企业微信管理、工…...

CountDownLatch的定义、使用 、原理

一、定义 CountDownLatch的作用很简单&#xff0c;就是一个或者一组线程在开始执行操作之前&#xff0c;必须要等到其他线程执行完才可以。我们举一个例子来说明&#xff0c;在考试的时候&#xff0c;老师必须要等到所有人交了试卷才可以走。此时老师就相当于等待线程&#xff…...

《Terraform 101 从入门到实践》 Terraform在公有云Azure上的应用

《Terraform 101 从入门到实践》这本小册在南瓜慢说官方网站和GitHub两个地方同步更新&#xff0c;书中的示例代码也是放在GitHub上&#xff0c;方便大家参考查看。 简介 Azure是微软的公有云&#xff0c;它提供了一些免费的资源&#xff0c;具体可以查看&#xff1a; https:/…...

别具一格,原创唯美浪漫情人节表白专辑,(复制就可用)(html5,css3,svg)表白爱心代码(3)

别具一格&#xff0c;原创唯美浪漫情人节表白专辑&#xff0c; (复制就可用)&#xff08;html5,css3,svg)表白爱心代码(3) 目录 款式三&#xff1a;心形实时显示认识多长时间桃花飞舞&#xff08;猫咪&#xff09;款 1、拷贝完整源代码 2、拷贝完整js代码 3、修改时间 4、…...

Linux 删除修改日期大于某一天的文件

在服务器运维过程中,我们往往会产生大量的日志文件. 如果日志文件命名能看出日志产生的时间,这些文件是很好删除的. 但有时,我们可能有成千上万的没有命名规律日志文件 下面的方法可以根据日志最后修改时间 批量删除这些文件 先给出完整命令: find /mydir -mtime 10 -name &…...

【算法题】1845. 座位预约管理系统

插&#xff1a; 前些天发现了一个巨牛的人工智能学习网站&#xff0c;通俗易懂&#xff0c;风趣幽默&#xff0c;忍不住分享一下给大家。点击跳转到网站。 坚持不懈&#xff0c;越努力越幸运&#xff0c;大家一起学习鸭~~~ 题目&#xff1a; 请你设计一个管理 n 个座位预约的系…...

DeepSeek 赋能智慧能源:微电网优化调度的智能革新路径

目录 一、智慧能源微电网优化调度概述1.1 智慧能源微电网概念1.2 优化调度的重要性1.3 目前面临的挑战 二、DeepSeek 技术探秘2.1 DeepSeek 技术原理2.2 DeepSeek 独特优势2.3 DeepSeek 在 AI 领域地位 三、DeepSeek 在微电网优化调度中的应用剖析3.1 数据处理与分析3.2 预测与…...

Cesium1.95中高性能加载1500个点

一、基本方式&#xff1a; 图标使用.png比.svg性能要好 <template><div id"cesiumContainer"></div><div class"toolbar"><button id"resetButton">重新生成点</button><span id"countDisplay&qu…...

五年级数学知识边界总结思考-下册

目录 一、背景二、过程1.观察物体小学五年级下册“观察物体”知识点详解&#xff1a;由来、作用与意义**一、知识点核心内容****二、知识点的由来&#xff1a;从生活实践到数学抽象****三、知识的作用&#xff1a;解决实际问题的工具****四、学习的意义&#xff1a;培养核心素养…...

均衡后的SNRSINR

本文主要摘自参考文献中的前两篇&#xff0c;相关文献中经常会出现MIMO检测后的SINR不过一直没有找到相关数学推到过程&#xff0c;其中文献[1]中给出了相关原理在此仅做记录。 1. 系统模型 复信道模型 n t n_t nt​ 根发送天线&#xff0c; n r n_r nr​ 根接收天线的 MIMO 系…...

人机融合智能 | “人智交互”跨学科新领域

本文系统地提出基于“以人为中心AI(HCAI)”理念的人-人工智能交互(人智交互)这一跨学科新领域及框架,定义人智交互领域的理念、基本理论和关键问题、方法、开发流程和参与团队等,阐述提出人智交互新领域的意义。然后,提出人智交互研究的三种新范式取向以及它们的意义。最后,总结…...

Golang——7、包与接口详解

包与接口详解 1、Golang包详解1.1、Golang中包的定义和介绍1.2、Golang包管理工具go mod1.3、Golang中自定义包1.4、Golang中使用第三包1.5、init函数 2、接口详解2.1、接口的定义2.2、空接口2.3、类型断言2.4、结构体值接收者和指针接收者实现接口的区别2.5、一个结构体实现多…...

抽象类和接口(全)

一、抽象类 1.概念&#xff1a;如果⼀个类中没有包含⾜够的信息来描绘⼀个具体的对象&#xff0c;这样的类就是抽象类。 像是没有实际⼯作的⽅法,我们可以把它设计成⼀个抽象⽅法&#xff0c;包含抽象⽅法的类我们称为抽象类。 2.语法 在Java中&#xff0c;⼀个类如果被 abs…...

js 设置3秒后执行

如何在JavaScript中延迟3秒执行操作 在JavaScript中&#xff0c;要设置一个操作在指定延迟后&#xff08;例如3秒&#xff09;执行&#xff0c;可以使用 setTimeout 函数。setTimeout 是JavaScript的核心计时器方法&#xff0c;它接受两个参数&#xff1a; 要执行的函数&…...

职坐标物联网全栈开发全流程解析

物联网全栈开发涵盖从物理设备到上层应用的完整技术链路&#xff0c;其核心流程可归纳为四大模块&#xff1a;感知层数据采集、网络层协议交互、平台层资源管理及应用层功能实现。每个模块的技术选型与实现方式直接影响系统性能与扩展性&#xff0c;例如传感器选型需平衡精度与…...

简约商务通用宣传年终总结12套PPT模版分享

IOS风格企业宣传PPT模版&#xff0c;年终工作总结PPT模版&#xff0c;简约精致扁平化商务通用动画PPT模版&#xff0c;素雅商务PPT模版 简约商务通用宣传年终总结12套PPT模版分享:商务通用年终总结类PPT模版https://pan.quark.cn/s/ece1e252d7df...