api文件怎么安装(网站api接口对接教程)

做积极的人,而不是积极废人!

源码精品专栏

原创 | Java 2020 超神之路,很肝~

中文详细注释的开源项目

RPC 框架 Dubbo 源码解析

网络应用框架 Netty 源码解析

消息中间件 RocketMQ 源码解析

数据库中间件 Sharding-JDBC 和 MyCAT 源码解析

作业调度中间件 Elastic-Job 源码解析

分布式事务中间件 TCC-Transaction 源码解析

Eureka 和 Hystrix 源码解析

Java 并发源码

1. 概述2. 快速入门 Swagger3. 更好看的 Swagger UI 界面4. 更强大的 YApi666. 彩蛋

本文在提供完整代码示例,可见 https://github.com/YunaiV/SpringBoot-Labs 的 lab-24 目录。

原创不易,给点个 Star 嘿,一起冲鸭!

1. 概述

目前,大多数系统都采用前后端分离。在享受前后端分离的好处的同时,接口联调往往成为团队效率的瓶颈,甚至产生前后端的矛盾。简单归结来说,有几方面的原因:

问题一,接口设计滞后。 后端团队往往不喜欢 API 接口设计先行,提前和前端沟通好接口。而在开发阶段的中后期,在后端提供 API 接口后,而这些接口和前端的预期有一些偏差,很容易就产生抱怨,特别是项目周期比较紧张的情况下。问题二,接口不规范。 当团队里没有同意明确的接口规范时,又或者代码 Review 做的不是很好的情况下,千奇百怪、各式各样的 API 接口可能就产生了。前端在对接这样的 API 接口,苦不堪言,在一口 mmp 一嘴 fuck xxx 之中,调完接口。问题三,接口文档更新不及时,或者遗忘更新。 因为后端 API 代码和 API 接口在两个地方,我们无法保证提交 API 代码的同时,及时更新文档。有的时候,我们甚至会遗忘更新 API 接口。随着时间的流逝,API 文档和 API 接口不一致的地方越来越多,前端会对 API 接口的信任度越来越低,然后不知道不觉之中,回到原始时代,直接问后端开发 API 是什么样的。

对于问题一和问题二,更多是开发流程上的问题,所以不在本文的范围内。当然话痨的艿艿,还是要给点粗浅的建议,完全拦不住我啊。

接口设计先行。设计完成后,后端和前端进行简单沟通,看看是否能够满足诉求。统一的接口规范。一定要制定统一的接口规范文档,即使比较简陋,也能保证团队的 API 接口相对统一一致。?? 即使错,咱也错的一模一样,而不是千奇百怪。当然,接口规范是无法覆盖到所有的场景的,借助于“接口设计先行”,我们可以提前去 Review 每个接口的设计。

对于问题三,就进入了本文的主角 Swagger 。通过在 API 接口上,添加相应的 Swagger 提供的注解,自动生成 API 文档。酱紫,API 接口和文档就在一起了,从此过上了幸福快乐的生活。

FROM 《RESTful 风格的 Web 服务框架 Swagger》

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

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

api文件怎么安装(网站api接口对接教程)预览图2. 快速入门 Swagger

示例代码对应仓库:lab-24-apidoc-swagger 。

在本小节,我们来快速入门 Swagger ,可以更加直观的感受到其提供的便利性。

2.1 引入依赖

在 pom.xml 文件中,引入相关依赖。

<?xmlversion=”1.0″encoding=”UTF-8″?><projectxmlns=”http://maven.apache.org/POM/4.0.0″xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd”><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/><!–lookupparentfromrepository–></parent><modelVersion>4.0.0</modelVersion><artifactId>lab-24-apidoc-swagger</artifactId><dependencies><!–实现对SpringMVC的自动化配置–><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!–引入Swagger依赖–><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!–引入SwaggerUI依赖,以实现API接口的UI界面–><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency></dependencies></project>

具体每个依赖的作用,胖友自己认真看下艿艿添加的所有注释噢。

2.2 SwaggerConfiguration

因为 Spring Boot 暂未提供 Swagger 内置的支持,所以我们需要自己定义配置类。

在 cn.iocoder.springboot.lab24.apidoc.config 包路径下,创建 SwaggerConfiguration 配置类,用于配置 Swagger 。代码如下:

//SwaggerConfiguration.java@Configuration@EnableSwagger2//标记项目启用SwaggerAPI接口文档publicclassSwaggerConfiguration{@BeanpublicDocketcreateRestApi(){//创建Docket对象returnnewDocket(DocumentationType.SWAGGER_2)//文档类型,使用Swagger2.apiInfo(this.apiInfo())//设置API信息//扫描Controller包路径,获得API接口.select().apis(RequestHandlerSelectors.basePackage(“cn.iocoder.springboot.lab24.apidoc.controller”)).paths(PathSelectors.any())//构建出Docket对象.build();}/***创建API信息*/privateApiInfoapiInfo(){returnnewApiInfoBuilder().title(“测试接口文档示例”).description(“我是一段描述”).version(“1.0.0”)//版本号.contact(newContact(“芋艿”,”http://www.iocoder.cn”,”zhijiantianya@gmail.com”))//联系人.build();}}在类上,添加 @EnableSwagger2 注解, 标记项目启用 Swagger API 接口文档。通过 #createRestApi() 方法,创建 Swagger Docket Bean 。每个属性的作用,胖友看看艿艿的注释。大多数情况下,胖友使用这些属性是足够的。不过如果想看看其它配置,胖友可以自己去如下两个类翻翻:Docket.javaApiInfo.java2.3 Application

创建 Application.java 类,配置 @SpringBootApplication 注解即可。代码如下:

//Application.java@SpringBootApplicationpublicclassApplication{publicstaticvoidmain(String[]args){SpringApplication.run(Application.class,args);}}

先暂时不启动项目。等我们添加好 Controller 。

2.4 UserController

在 cn.iocoder.springboot.lab24.apidoc.controller 包路径下,创建 UserController 类,提供用户 API 接口。代码如下:

//UserController.java@RestController@RequestMapping(“/users”)@Api(tags=”用户API接口”)publicclassUserController{@GetMapping(“/list”)@ApiOperation(value=”查询用户列表”,notes=”目前仅仅是作为测试,所以返回用户全列表”)publicList<UserVO>list(){//查询列表List<UserVO>result=newArrayList<>();result.add(newUserVO().setId(1).setUsername(“yudaoyuanma”));result.add(newUserVO().setId(2).setUsername(“woshiyutou”));result.add(newUserVO().setId(3).setUsername(“chifanshuijiao”));//返回列表returnresult;}@GetMapping(“/get”)@ApiOperation(“获得指定用户编号的用户”)@ApiImplicitParam(name=”id”,value=”用户编号”,paramType=”query”,dataTypeClass=Integer.class,required=true,example=”1024″)publicUserVOget(@RequestParam(“id”)Integerid){//查询并返回用户returnnewUserVO().setId(id).setUsername(UUID.randomUUID().toString());}@PostMapping(“add”)@ApiOperation(“添加用户”)publicIntegeradd(UserAddDTOaddDTO){//插入用户记录,返回编号IntegerreturnId=UUID.randomUUID().hashCode();//返回用户编号returnreturnId;}@PostMapping(“/update”)@ApiOperation(“更新指定用户编号的用户”)publicBooleanupdate(UserUpdateDTOupdateDTO){//更新用户记录Booleansuccess=true;//返回更新是否成功returnsuccess;}@PostMapping(“/delete”)@ApiOperation(value=”删除指定用户编号的用户”)@ApiImplicitParam(name=”id”,value=”用户编号”,paramType=”query”,dataTypeClass=Integer.class,required=true,example=”1024″)publicBooleandelete(@RequestParam(“id”)Integerid){//删除用户记录Booleansuccess=false;//返回是否更新成功returnsuccess;}}相比我们之前使用 SpringMVC 来说,我们在类和接口上,额外增加了 Swagger 提供的注解。从使用习惯上,我比较喜欢先添加 SpringMVC 的注解,再添加 Swagger 的注解。因为已经使用了 Swagger 的注解,所以类和方法上的注释,一般可以删除了,除非有特殊诉求。其中涉及到的 POJO 类,有 UserAddDTO、UserUpdateDTO、UserVO 。

至此,我们已经完成了 Swagger 的快速入门。不过考虑到胖友能够更好的使用,我们来一个一个注解了解。

2.5 注解

在 swagger-annotations 库中,在 io.swagger.annotations 包路径下,提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的,大多数场景下,只需要使用到我们在 「2.4 UserController」 中用到的注解。

2.5.1 @Api

@Api 注解,添加在 Controller 类上,标记它作为 Swagger 文档资源。

示例如下:

//UserController.java@RestController@RequestMapping(“/users”)@Api(tags=”用户API接口”)publicclassUserController{//…省略}

效果如下:

@Api 注解的常用属性,如下:

tags 属性:用于控制 API 所属的标签列表。[] 数组,可以填写多个。可以在一个 Controller 上的 @Api 的 tags 属性,设置多个标签,那么这个 Controller 下的 API 接口,就会出现在这两个标签中。如果在多个 Controller 上的 @Api 的 tags 属性,设置一个标签,那么这些 Controller 下的 API 接口,仅会出现在这一个标签中。本质上,tags 就是为了分组 API 接口,和 Controller 本质上是一个目的。所以绝大数场景下,我们只会给一个 Controller 一个唯一的标签。例如说,UserController 的 tags 设置为 “用户 API 接口” 。

@Api 注解的不常用属性,如下:

produces 属性:请求请求头的可接受类型( Accept )。如果有多个,使用 , 分隔。consumes 属性:请求请求头的提交内容类型( Content-Type )。如果有多个,使用 , 分隔。protocols 属性:协议,可选值为 “http”、”https”、”ws”、”wss” 。如果有多个,使用 , 分隔。authorizations 属性:授权相关的配置,[] 数组,使用 @Authorization 注解。hidden 属性:是否隐藏,不再 API 接口文档中显示。

@Api 注解的废弃属性,不建议使用,有 value、description、basePath、position 。

2.5.2 @ApiOperation

@ApiOperation 注解,添加在 Controller 方法上,标记它是一个 API 操作。

示例如下:

//UserController.java@GetMapping(“/list”)@ApiOperation(value=”查询用户列表”,notes=”目前仅仅是作为测试,所以返回用户全列表”)publicList<UserVO>list(){//查询列表List<UserVO>result=newArrayList<>();result.add(newUserVO().setId(1).setUsername(“yudaoyuanma”));result.add(newUserVO().setId(2).setUsername(“woshiyutou”));result.add(newUserVO().setId(3).setUsername(“chifanshuijiao”));//返回列表returnresult;}

效果如下:

@ApiOperation 注解的常用属性,如下:

value 属性:API 操作名。notes 属性:API 操作的描述。

@ApiOperation 注解的不常用属性,如下:

tags 属性:和 @API 注解的 tags 属性一致。nickname 属性:API 操作接口的唯一标识,主要用于和第三方工具做对接。httpMethod 属性:请求方法,可选值为 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH 。因为 Swagger 会解析 SpringMVC 的注解,所以一般无需填写。produces 属性:和 @API 注解的 produces 属性一致。consumes 属性:和 @API 注解的 consumes 属性一致。protocols 属性:和 @API 注解的 protocols 属性一致。authorizations 属性:和 @API 注解的 authorizations 属性一致。hidden 属性:和 @API 注解的 hidden 属性一致。response 属性:响应结果类型。因为 Swagger 会解析方法的返回类型,所以一般无需填写。responseContainer 属性:响应结果的容器,可选值为 List、Set、Map 。responseReference 属性:指定对响应类型的引用。这个引用可以是本地,也可以是远程。并且,当设置了它时,会覆盖 response 属性。说人话,就是可以忽略这个属性,哈哈哈。responseHeaders 属性:响应头,[] 数组,使用 @ResponseHeader 注解。code 属性:响应状态码,默认为 200 。extensions 属性:拓展属性,[] 属性,使用 @Extension 注解。ignoreJsonView 属性:在解析操作和类型,忽略 JsonView 注释。主要是为了向后兼容。

@ApiOperation 注解的废弃属性,不建议使用,有 position 。

2.5.3 @ApiImplicitParam

@ApiImplicitParam 注解,添加在 Controller 方法上,声明每个请求参数的信息。

示例如下:

//UserController.java@PostMapping(“/delete”)@ApiOperation(value=”删除指定用户编号的用户”)@ApiImplicitParam(name=”id”,value=”用户编号”,paramType=”query”,dataTypeClass=Integer.class,required=true,example=”1024″)publicBooleandelete(@RequestParam(“id”)Integerid){//删除用户记录Booleansuccess=false;//返回是否更新成功returnsuccess;}

效果如下:

@ApiImplicitParam 注解的常用属性,如下:

name 属性:参数名。value 属性:参数的简要说明。required 属性:是否为必传参数。默认为 false 。dataType 属性:数据类型,通过字符串 String 定义。dataTypeClass 属性:数据类型,通过 dataTypeClass 定义。在设置了 dataTypeClass 属性的情况下,会覆盖 dataType 属性。推荐采用这个方式。paramType 属性:参数所在位置的类型。有如下 5 种方式:”path” 值:对应 SpringMVC 的 @PathVariable 注解。【默认值】”query” 值:对应 SpringMVC 的 @PathVariable 注解。”body” 值:对应 SpringMVC 的 @RequestBody 注解。”header” 值:对应 SpringMVC 的 @RequestHeader 注解。”form” 值:Form 表单提交,对应 SpringMVC 的 @PathVariable 注解。?? 绝大多数情况下,使用 “query” 值这个类型即可。example 属性:参数值的简单示例。examples 属性:参数值的复杂示例,使用 @Example 注解。

@ApiImplicitParam 注解的不常用属性,如下:

defaultValue 属性:默认值。allowableValues 属性:允许的值。如果要设置多个值,有两种方式:数组方式,即 {value1, value2, value3} 。例如说,{1, 2, 3} 。范围方式,即 [value1, value2] 或 [value1, value2) 。例如说 [1, 5] 表示 1 到 5 的所有数字。如果有无穷的,可以使用 (-infinity, value2] 或 [value1, infinity) 。allowEmptyValue 属性:是否允许空值。allowMultiple 属性:是否允许通过多次传递该参数来接受多个值。默认为 false 。type 属性:搞不懂具体用途,对应英文注释为 Adds the ability to override the detected type 。readOnly 属性:是否只读。format 属性:自定义的格式化。collectionFormat 属性:针对 Collection 集合的,自定义的格式化。

当我们需要添加在方法上添加多个 @ApiImplicitParam 注解时,可以使用 @ApiImplicitParams 注解中添加多个。示例如下:

@ApiImplicitParams({//参数数组@ApiImplicitParam(name=”id”,value=”用户编号”,paramType=”query”,dataTypeClass=Integer.class,required=true,example=”1024″),//参数一@ApiImplicitParam(name=”name”,value=”昵称”,paramType=”query”,dataTypeClass=String.class,required=true,example=”芋道”),//参数二})2.5.4 @ApiModel

@ApiModel 注解,添加在 POJO 类,声明 POJO 类的信息。而在 Swagger 中,把这种 POJO 类称为 Model 类。所以,我们下文就统一这么称呼。

示例如下:

//UserVO.java@ApiModel(“用户VO”)publicclassUserVO{//…省略}

效果如下:

@ApiModel 注解的常用属性,如下:

value 属性:Model 名字。description 属性:Model 描述。

@ApiModel 注解的不常用属性,如下:

parent 属性:指定该 Model 的父 Class 类,用于继承父 Class 的 Swagger 信息。subTypes 属性:定义该 Model 类的子类 Class 们。discriminator 属性:搞不懂具体用途,对应英文注释为 Supports model inheritance and polymorphism.reference 属性:搞不懂具体用途,对应英文注释为 Specifies a reference to the corresponding type definition, overrides any other metadata specified2.5.5 @ApiModelProperty

@ApiModelProperty 注解,添加在 Model 类的成员变量上,声明每个成员变量的信息。

示例如下:

//UserVO.java@ApiModel(“用户VO”)publicclassUserVO{@ApiModelProperty(value=”用户编号”,required=true,example=”1024″)privateIntegerid;@ApiModelProperty(value=”账号”,required=true,example=”yudaoyuanma”)privateStringusername;//…省略set/get方法}

效果如下:

@ApiModelProperty 注解的常用属性,如下:

value 属性:属性的描述。dataType 属性:和 @ApiImplicitParam 注解的 dataType 属性一致。不过因为 @ApiModelProperty 是添加在成员变量上,可以自动获得成员变量的类型。required 属性:和 @ApiImplicitParam 注解的 required 属性一致。example 属性:@ApiImplicitParam 注解的 example 属性一致。

@ApiModelProperty 注解的不常用属性,如下:

name 属性:覆盖成员变量的名字,使用该属性进行自定义。allowableValues 属性:和 @ApiImplicitParam 注解的 allowableValues 属性一致。position 属性:成员变量排序位置,默认为 0 。hidden 属性:@ApiImplicitParam 注解的 hidden 属性一致。accessMode 属性:访问模式,有 AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE 三种,默认为 AccessMode.AUTO 。reference 属性:和 @ApiModel 注解的 reference 属性一致。allowEmptyValue 属性:和 @ApiImplicitParam 注解的 allowEmptyValue 属性一致。extensions 属性:和 @ApiImplicitParam 注解的 extensions 属性一致。

@ApiModelProperty 注解的废弃属性,不建议使用,有 readOnly 。

2.5.6 @ApiResponse

在大多数情况下,我们并不需要使用 @ApiResponse 注解,因为我们会类似 UserController#get(id) 方法这个接口,返回一个 Model 即可。所以 @ApiResponse 注解,艿艿就简单讲解,嘿嘿。

@ApiResponse 注解,添加在 Controller 类的方法上,声明每个响应参数的信息。

@ApiResponse 注解的属性,基本已经被 @ApiOperation 注解所覆盖,如下:

message 属性:响应的提示内容。code 属性:和 @ApiOperation 注解的 code 属性一致。response 属性:和 @ApiOperation 注解的 response 属性一致。reference 属性:和 @ApiOperation 注解的 responseReference 属性一致。responseHeaders 属性:和 @ApiOperation 注解的 responseHeaders 属性一致。responseContainer 属性:和 @ApiOperation 注解的 responseContainer 属性一致。examples 属性:和 @ApiOperation 注解的 examples 属性一致。

当我们需要添加在方法上添加多个 @ApiResponse 注解时,可以使用 @ApiResponses 注解中添加多个。

至此,我们已经了解完 Swagger 项目中提供的主要注解。如果想要看到更多的 Swagger 的使用示例,可以看看艿艿开源的 onemall 项目。

咳咳咳,整理 Swagger 注解的每个属性,真的是花费时间。如果有哪个解释不到位,请一定给艿艿留言,我去优化和调整下,嘻嘻。

2.6 测试接口

在三个红圈中,我们可以看到 Swagger 给我们提供了:

?? 当然,实际项目开发中,艿艿还是喜欢 Postman 来测试接口,嘿嘿。

3. 更好看的 Swagger UI 界面

示例代码对应仓库:lab-24-apidoc-swagger-knife4j 。

springfox-swagger-ui 提供的 UI 界面,基本能够满足我们的日常使用,但是距离好用,还是有一段距离。幸福的是,社区有人开源了 swagger-bootstrap-ui 项目,提供更好看且好用的 UI 界面。

具体的演示示例,可以访问:http://swagger-bootstrap-ui.xiaominfo.com/doc.html 查看。

在 「2. 快速入门 Swagger」 的 lab-24-apidoc-swagger 示例的基础上,我们复制出 lab-24-apidoc-swagger-knife4j 项目,进行改造。

3.1 修改依赖

在 pom.xml 文件中,修改相关依赖。

<?xmlversion=”1.0″encoding=”UTF-8″?><projectxmlns=”http://maven.apache.org/POM/4.0.0″xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd”><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.3.RELEASE</version><relativePath/><!–lookupparentfromrepository–></parent><modelVersion>4.0.0</modelVersion><artifactId>lab-24-apidoc-swagger-knife4j</artifactId><dependencies><!–实现对SpringMVC的自动化配置–><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!–1.swagger-bootstrap-ui目前改名为knife4j–><!–2.实现swagger-bootstrap-ui的自动化配置–><!–3.因为knife4j-spring已经引入Swagger依赖,所以无需重复引入–><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring</artifactId><version>1.9.6</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-ui</artifactId><version>1.9.6</version></dependency></dependencies></project>

具体每个依赖的作用,胖友自己认真看下艿艿添加的所有注释噢。

3.2 界面一览

直接使用 Application 启动项目,无需做其它任何的变更,方便的说。

?? 注意下,界面上艿艿添加的红圈和红字噢。更多功能,胖友自己看 官方文档 哟。非常推荐生产中,使用它,嘿嘿。

4. 更强大的 YApi

虽然说 Swagger 已经挺强大了,可以很好的完成提供后端 API 接口文档的功能,但是实际场景下,我们还是会碰到很多问题:

Swagger 没有内置 Mock 功能。在实际的开发中,在后端定义好 API 接口之后,前端会根据 API 接口,进行接口的 Mock ,从而实现前后端的并行开发。多个项目的 API 接口文档的整合。随着微服务的流行,一个产品实际是拆分成多个微服务项目,提供 API 接口。那么,一个微服务项目,一个接口文档,肯定会气死前端。气死一个前端小哥哥没事,如果是小姐姐那多可惜啊。

所以,我们需要更加强大的 API 接口管理平台。目前艿艿团队采用的解决方案是:

后端开发,还是使用 Swagger 注解,生成 API 接口文档。使用 YApi 可视化接口管理平台,自动调用 Swagger 提供的 v2/api-docs 接口,采集 Swagger 注解生成的 API 接口信息,从而录入到 YApi 中。

这样,我们既可以享受到 Swagger 带给我们编写 API 接口文档的便利性与及时性,又能享受到 YApi 的强大功能。

FROM https://github.com/YMFE/yapi

基于 Json5 和 Mockjs 定义接口返回数据的结构和文档,效率提升多倍扁平化权限设计,即保证了大型企业级项目的管理,又保证了易用性类似 postman 的接口调试自动化测试, 支持对 Response 断言MockServer 除支持普通的随机 mock 外,还增加了 Mock 期望功能,根据设置的请求过滤规则,返回期望数据支持 postman, har, swagger 数据导入免费开源,内网部署,信息再也不怕泄露了

下面,我们就一起来搭建一个 YApi 平台,美滋滋。因为 YApi 基于 NodeJS 语言开发,使用 MongoDB 作为数据库存储接口信息,所以我们需要先安装 NodeJS 和 MongoDB 。

艿艿:目前手头上只有 MacOS 和 CentOS 环境,所以如下的步骤,暂支也只保证这两个环境,抱歉~

如果使用 Windows 或者 Ubuntu 的同学,请辛苦自行解决下。

4.1 安装 MongoDB

参考 《芋道 MongoDB 极简入门》 文章,先进行下安装 MongoDB 数据库。

安装完成,记得参考文章,创建一个 yapi 数据库,后续我们会使用到。

4.2 安装 NodeJS

如果胖友是 CentOS 环境,使用 yum install nodejs 命令,进行安装。

如果胖友是 MacOS 环境,使用 brew install node 命令,进行安装。如果没有 brew 的胖友,这么 666 的神器,不赶紧安装下嘛?!

4.3 安装 yapi-cli

#安装yapi-cli工具$npminstall-gyapi-cli–registryhttps://registry.npm.taobao.org#启动YApi平台部署工具$yapiserver在浏览器打开http://0.0.0.0:9090访问。非本地服务器,请将0.0.0.0替换成指定的域名或ip4.4 YApi 平台部署

耐心等待,直到出现日志如下:

初始化管理员账号成功,账号名:”zhijiantianya@gmail.com”,密码:”ymfe.org”部署成功,请切换到部署目录,输入:”nodevendors/server/app.js”指令启动服务器,然后在浏览器打开http://127.0.0.1:3000访问

此时,我们可以在命令行执行 ctrl-c 操作,关闭YApi 平台部署工具。

4.5 YApi 平台启动

在命令行中,执行如下命令,启动 YApi 平台。

#进入yapi部署路径$cd/Users/yunai/my-yapi/#启动yapi平台$nodevendors/server/app.jslog:————————————-swaggerSyncUtilsconstructor———————————————–log:服务已启动,请打开下面链接访问:http://127.0.0.1:3000/log:mongodbloadsuccess…

项目启动完成。如果真正开始使用时,建议使用 pm2 方便服务管理维护。命令如下:

npminstallpm2-g//安装pm2cd{项目目录}pm2start”vendors/server/app.js”–nameyapi//pm2管理yapi服务pm2infoyapi//查看服务信息pm2stopyapi//停止服务pm2restartyapi//重启服务

这里,我们可以先略过这个操作,继续往下看。毕竟,咱现在的重心是先入门。

4.5 创建项目

4.6 设置 Swagger 自动同步

实际上,无论是 Swagger UI 也是基于该接口,获得 API 接口信息。

至此,我们已经完成搭建 YApi 平台,并自动采集 Swagger 提供的 API 接口信息。YApi 的功能非常强大,一定要翻一翻 官方文档 哟。例如说,数据 Mock、高级 Mock 、自动化测试等等功能,都是非常值得在项目中实践使用。

666. 彩蛋

那么,在有了 API 接口文档之后,如何和前端更好的沟通呢?

当然,做标记的原则是,需要跟产品协商好可以用来标记的区域,不能影响到他们的工作。例如说:

友情提示:Axure 也是支持 团队协作 的噢。如果胖友家的产品还没使用,批评(怒喷)一下他们。

这样,在原型上标记好接口之后,我们就可以找前端妹子,对着原型,顺着接口走一遍流程。如果走的很顺畅,说明咱的接口棒棒的。嘿嘿~

一定要记住,工具仅仅是工具,一定要尽早达成前后端的一致。

下面,进入话痨艿艿的碎碎念环节,分享下艿艿在 API 接口文档的心路历程。

在 2011 年的时候,开始第一份工作的实习。公司管理后台前端采用的是 ExtJS ,后端使用 SpringMVC 提供接口。架构还是采用前后端分离,不过前端 JS 代码还是后端开发来编写,所以也就不存在 API 接口文档一说了。这个时候,更多的是自我约束,强制自己先设计好 API 接口,然后顺着产品原型走一圈。如果没问题,就开始编写后端 API 接口的实现。完成之后,在编写前端 JS 代码~

在 2013 年的时候,开始了又一次创业的遨游。项目的前端是 iOS 和 Android 客户端,顺理成章的还是前后端分离。因为客户端分成 iOS 和 Android 客户端版本,并且还是两个不同的开发小哥(是的,竟然没一个是小姐姐),所以艿艿只好提供 API 接口的文档。这个时候的 API 接口的文档方案比较土,土豆的土,使用的是 Word 文档 SVN 协作。可想而知,大几十页的,一点打开的欲望都没有。?? 更痛苦的是,Word 文档的内容,是不支持 SVN 比对合并的,这就导致未来的一段时间,我们发展到 10 后端开发的时候,疯狂的冲突。

在 2015 年的时候,差不多是这个点吧,记忆有点模糊了。我们开始使用 Confluence 作为我们的 Wiki 工具,新的 API 接口文档自然就被调整到在上面编写,而老的 API 接口慢慢迁移上来。带来的好处不言而喻,终于解决多人协作老冲突的问题。同时,Confluence 支持 Template 模板,也比较容易的控制 API 接口的格式和规范。当然,比较大的困扰,还是文头提到的问题三,经常有同学忘记更新 API 文档,导致代码和文档越来越不一致。

在 2016 年的时候,爱倒腾的艿艿,无意中发现网易提供的 NEI 接口管理平台。当时从 Confluence 替换成 NEI 的原因,有点不太记得,好像是 NEI 更加结构化,也更加专业。毕竟,Confluence 是一个 Wiki 工具,而不是专为 API 接口设计的管理平台。当然,此时问题三还是存在的。

在 2019 年的时候,刚好开始了一个新项目,抱着比较尝试的心态,使用了 Swagger 来编写接口文档,效果其好,主要也是解决了问题三。更舒服的是,相比 NEI 上编写接口文档,?? 可以复制粘贴代码,效率也提升了蛮多。

再后来,我们引入了 YApi 接口管理平台,形成了我们 Swagger YApi Axure 标记的整体方案。大体就是酱紫。深夜 02:16 了,结束今天的哔哔,迎接明天的哔哔。

欢迎加入我的知识星球,一起探讨架构,交流源码。加入方式,长按下方二维码噢:

发表评论

登录后才能评论