写Api接口神器,带你5分钟了解Swagger
yuyutoo 2024-10-12 01:50 5 浏览 0 评论
一、前言
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
记住,最重要的,可以自动扫描接口生成文档,解决文档更新不及时问题!!!
二、springfox介绍
由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来,而springfox则是从这个组件发展而来。
通常SpringBoot项目整合swagger需要用到两个依赖: springfox-swagger2 和 springfox-swagger-ui ,用于自动生成swagger文档。
- springfox-swagger2:这个组件的功能用于帮助我们自动生成描述API的json文件
- springfox-swagger-ui:就是将描述API的json文件解析出来,用一种更友好的方式呈现出来。
三、SpringFox 3.0.0 发布
官方说明:
SpringFox 3.0.0 发布了,SpringFox 的前身是 swagger-springmvc,是一个开源的 API doc 框架,可以将 Controller 的方法以文档的形式展现。
新特性:
- Remove explicit dependencies on springfox-swagger2
- Remove any @EnableSwagger2… annotations
- Add the springfox-boot-starter dependency
- Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.
此版本的亮点:
- Spring5,Webflux支持(仅支持请求映射,尚不支持功能端点)。
- Spring Integration支持(非常感谢反馈)。
- SpringBoot支持 springfox Boot starter 依赖性(零配置、自动配置支持)。
- 具有自动完成功能的文档化配置属性。
- 更好的规范兼容性与2.0。
- 支持OpenApi 3.0.3。
- 零依赖。几乎只需要spring-plugin,swagger-core ,现有的swagger2注释将继续工作并丰富openapi3.0规范。
兼容性说明:
- 需要Java 8
- 需要Spring5.x(未在早期版本中测试)
- 需要SpringBoot 2.2+(未在早期版本中测试)
注意:
应用主类增加注解 @EnableOpenApi ,删除之前版本的SwaggerConfig.java。
启动项目,访问地址: http://localhost:8080/swagger-ui/index.html ,注意2.x版本中访问的地址的为 http://localhost:8080/swagger-ui.html
四、Springboot整合Springfox 3.0使用
1、maven依赖添加
Maven项目中引入 springfox-boot-starter 依赖:
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-boot-starterartifactId>
<version>3.0.0version>
dependency>
2、application.yml配置
注意:配置文件建议用yml,原因在配置类的地方说。
swagger:
application-description: springfox swagger 3.0 整合Demo
application-name: hahha
application-version: 1.0
enable: true
try-host: http://localhost:8080
3、定义属性类SwaggerProperties读取前面配置文件内容
@Component
@ConfigurationProperties("swagger")
//ConfigurationProperties读取配置文件时,默认是ISO_8859_1编码,所以需要指定application.properties以外的配置文件,使用utf-8编码
//或者是用yaml文件名,读取yaml默认是utf-8编码
//或者是将utf8转换成ascall码放在properties配置文件中
//@PropertySource(value="classpath:application1.properties", encoding="UTF-8")
//我们这里用yaml方式
public class SwaggerProperties {
/**
* 是否开启swagger,生产环境一般关闭,所以这里定义一个变量
*/
private Boolean enable;
/**
* 项目应用名
*/
private String applicationName;
/**
* 项目版本信息
*/
private String applicationVersion;
/**
* 项目描述信息
*/
private String applicationDescription;
/**
* 接口调试地址
*/
private String tryHost;
public Boolean getEnable() {
return enable;
}
public void setEnable(Boolean enable) {
this.enable = enable;
}
public String getApplicationName() {
return applicationName;
}
public void setApplicationName(String applicationName) {
this.applicationName = applicationName;
}
public String getApplicationVersion() {
return applicationVersion;
}
public void setApplicationVersion(String applicationVersion) {
this.applicationVersion = applicationVersion;
}
public String getApplicationDescription() {
return applicationDescription;
}
public void setApplicationDescription(String applicationDescription) {
this.applicationDescription = applicationDescription;
}
public String getTryHost() {
return tryHost;
}
public void setTryHost(String tryHost) {
this.tryHost = tryHost;
}
}
4、定义配置类,提供Docket实例
@EnableOpenApi
@Configuration
public class SwaggerConfig {
private final SwaggerProperties swaggerProperties;
public SwaggerConfig(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).pathMapping("/")
// 定义是否开启swagger,false为关闭,可以通过变量控制
.enable(swaggerProperties.getEnable())
// 将api的元信息设置为包含在json ResourceListing响应中。
.apiInfo(apiInfo())
// 接口调试地址
.host(swaggerProperties.getTryHost())
// 选择哪些接口作为swagger的doc发布
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //指定package下的请求路径
// .apis(RequestHandlerSelectors.any()) //任意请求路径
.build()
.groupName("测试swagger系统")
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
// 授权信息设置,必要的header token等认证信息
.securitySchemes(securitySchemes())
// 授权信息全局应用
.securityContexts(securityContexts());
}
@Bean
public Docket createRestApi2() {
return new Docket(DocumentationType.OAS_30).pathMapping("/")
// 定义是否开启swagger,false为关闭,可以通过变量控制
.enable(swaggerProperties.getEnable())
// 将api的元信息设置为包含在json ResourceListing响应中。
.apiInfo(apiInfo())
// 接口调试地址
.host(swaggerProperties.getTryHost())
// 选择哪些接口作为swagger的doc发布
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.groupName("测试swagger2系统")
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
// 授权信息设置,必要的header token等认证信息
.securitySchemes(securitySchemes())
// 授权信息全局应用
.securityContexts(securityContexts());
}
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
.description(swaggerProperties.getApplicationDescription())
.contact(new Contact("lighter", null, "123456@gmail.com"))
.version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
.build();
}
/**
* 设置授权信息
*/
private List securitySchemes() {
ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
return Collections.singletonList(apiKey);
}
/**
* 授权信息全局应用
*/
private List securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
.build()
);
}
@SafeVarargs
private final <T> Set newHashSet(T... ts) {
if (ts.length > 0) {
return new LinkedHashSet<>(Arrays.asList(ts));
}
return null;
}
}
5、在接口中,添加接口说明
import io.swagger.annotations.*;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import javax.validation.Valid;
import javax.validation.constraints.*;
import java.util.ArrayList;
import java.util.List;
@Api(tags = "用户管理")
@RestController
public class UserController {
@ApiOperation("创建用户")
@PostMapping("/users")
public User create(@RequestBody @Valid User user) {
return user;
}
@ApiOperation("用户详情")
@GetMapping("/users/{id}")
public User findById(@PathVariable Long id) {
return new User("bbb", 21, "上海", "aaa@bbb.com");
}
@ApiOperation("用户列表")
@GetMapping("/users")
public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
@ApiParam("每页多少条") @RequestParam int pageSize) {
List<User> result = new ArrayList<>();
result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
return result;
}
@ApiIgnore
@DeleteMapping("/users/{id}")
public String deleteById(@PathVariable Long id) {
return "delete user : " + id;
}
}
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户基本信息")
class User {
@ApiModelProperty("姓名")
@Size(max = 20)
private String name;
@ApiModelProperty("年龄")
@Max(150)
@Min(1)
private Integer age;
@NotNull
private String address;
@Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+#34;)
private String email;
}
一些常用注解说明
- @Api:用在controller类,描述API接口
- @ApiOperation:描述接口方法
- @ApiModel:描述对象
- @ApiModelProperty:描述对象属性
- @ApiImplicitParams:描述接口参数
- @ApiResponses:描述接口响应
- @ApiIgnore:忽略接口方法
相关推荐
- 自卑的人容易患抑郁症吗?(自卑会导致抑郁吗)
-
Filephoto[Photo/IC]Lowself-esteemmakesusfeelbadaboutourselves.Butdidyouknowthatovert...
- 中考典型同(近)义词组(同义词考题)
-
中考典型同(近)义词组...
- BroadcastReceiver的原理和使用(broadcast-suppression)
-
一、使用中注意的几点1.动态注册、静态注册的优先级在AndroidManifest.xml中静态注册的receiver比在代码中用registerReceiver动态注册的优先级要低。发送方在send...
- Arduino通过串口透传ESP 13板与java程序交互
-
ESP13---是一个无线板子,配置通过热点通信Arduino通过串口透传ESP13板与java程序交互...
- zookeeper的Leader选举源码解析(zookeeper角色选举角色包括)
-
作者:京东物流梁吉超zookeeper是一个分布式服务框架,主要解决分布式应用中常见的多种数据问题,例如集群管理,状态同步等。为解决这些问题zookeeper需要Leader选举进行保障数据的强一致...
- 接待外国人英文口语(接待外国友人的英语口语对话)
-
接待外国人英文口语询问访客身份: MayIhaveyourname,please? 请问您贵姓? Whatcompanyareyoufrom? 您是哪个公司的? Could...
- 一文深入理解AP架构Nacos注册原理
-
Nacos简介Nacos是一款阿里巴巴开源用于管理分布式微服务的中间件,能够帮助开发人员快速实现动态服务发现、服务配置、服务元数据及流量管理等。这篇文章主要剖析一下Nacos作为注册中心时其服务注册与...
- Android面试宝典之终极大招(android面试及答案)
-
以下内容来自兆隆IT云学院就业部,根据多年成功就业服务经验,以及职业素养课程部分内容,归纳总结:18.请描述一下Intent和IntentFilter。Android中通过Intent...
- 除了Crontab,Swoole Timer也可以实现定时任务的
-
一般的定时器是怎么实现的呢?我总结如下:1.使用Crontab工具,写一个shell脚本,在脚本中调用PHP文件,然后定期执行该脚本;2.ignore_user_abort()和set_time_li...
- Spark源码阅读:DataFrame.collect 作业提交流程思维导图
-
本文分为两个部分:作业提交流程思维导图关键函数列表作业提交流程思维导图...
- 使用Xamarin和Visual Studio开发Android可穿戴设备应用
-
搭建开发环境我们需要做的第一件事情是安装必要的工具。因此,你需要首先安装VisualStudio。如果您使用的是VisualStudio2010,2012或2013,那么请确保它是一个专业版本或...
- Android开发者必知的5个开源库(android 开发相关源码精编解析)
-
过去的时间里,Android开发逐步走向成熟,一个个与Android相关的开发工具也层出不穷。不过,在面对各种新鲜事物时,不要忘了那些我们每天使用的大量开源库。在这里,向大家介绍的就是,在这个任劳任怨...
- Android事件总线还能怎么玩?(android实现事件处理的步骤)
-
顾名思义,AndroidEventBus是一个Android平台的事件总线框架,它简化了Activity、Fragment、Service等组件之间的交互,很大程度上降低了它们之间的耦合,使我们的代码...
- Android 开发中文引导-应用小部件
-
应用小部件是可以嵌入其它应用(例如主屏幕)并收到定期更新的微型应用视图。这些视图在用户界面中被叫做小部件,并可以用应用小部件提供者发布。可以容纳其他应用部件的应用组件叫做应用部件的宿主(1)。下面的截...
你 发表评论:
欢迎- 一周热门
-
-
前端面试:iframe 的优缺点? iframe有那些缺点
-
带斜线的表头制作好了,如何填充内容?这几种方法你更喜欢哪个?
-
漫学笔记之PHP.ini常用的配置信息
-
推荐7个模板代码和其他游戏源码下载的网址
-
其实模版网站在开发工作中很重要,推荐几个参考站给大家
-
[干货] JAVA - JVM - 2 内存两分 [干货]+java+-+jvm+-+2+内存两分吗
-
正在学习使用python搭建自动化测试框架?这个系统包你可能会用到
-
织梦(Dedecms)建站教程 织梦建站详细步骤
-
【开源分享】2024PHP在线客服系统源码(搭建教程+终身使用)
-
2024PHP在线客服系统源码+完全开源 带详细搭建教程
-
- 最近发表
-
- 自卑的人容易患抑郁症吗?(自卑会导致抑郁吗)
- 中考典型同(近)义词组(同义词考题)
- WPF 消息传递简明教程(wpf messagebox.show)
- BroadcastReceiver的原理和使用(broadcast-suppression)
- Arduino通过串口透传ESP 13板与java程序交互
- zookeeper的Leader选举源码解析(zookeeper角色选举角色包括)
- 接待外国人英文口语(接待外国友人的英语口语对话)
- 一文深入理解AP架构Nacos注册原理
- Android面试宝典之终极大招(android面试及答案)
- 除了Crontab,Swoole Timer也可以实现定时任务的
- 标签列表
-
- mybatis plus (70)
- scheduledtask (71)
- css滚动条 (60)
- java学生成绩管理系统 (59)
- 结构体数组 (69)
- databasemetadata (64)
- javastatic (68)
- jsp实用教程 (53)
- fontawesome (57)
- widget开发 (57)
- vb net教程 (62)
- hibernate 教程 (63)
- case语句 (57)
- svn连接 (74)
- directoryindex (69)
- session timeout (58)
- textbox换行 (67)
- extension_dir (64)
- linearlayout (58)
- vba高级教程 (75)
- iframe用法 (58)
- sqlparameter (59)
- trim函数 (59)
- flex布局 (63)
- contextloaderlistener (56)