长春网站排名提升,seo关键词推广多少钱,企业seo顾问服务公司,天津百度百科转载自 芋道 Spring Boot API 接口文档 Swagger 入门 摘要: 原创出处 http://www.iocoder.cn/Spring-Boot/Swagger/ 「芋道源码」欢迎转载#xff0c;保留摘要#xff0c;谢谢#xff01; 本文在提供完整代码示例#xff0c;可见 https://github.com/YunaiV/SpringBoot-Lab…转载自 芋道 Spring Boot API 接口文档 Swagger 入门 摘要: 原创出处 http://www.iocoder.cn/Spring-Boot/Swagger/ 「芋道源码」欢迎转载保留摘要谢谢 本文在提供完整代码示例可见 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 从未如此简单。 预览图
2. 快速入门 Swagger 示例代码对应仓库lab-24-apidoc-swagger 。 在本小节我们来快速入门 Swagger 可以更加直观的感受到其提供的便利性。
2.1 引入依赖
在 pom.xml 文件中引入相关依赖。
?xml version1.0 encodingUTF-8?
project xmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsdparentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion2.1.3.RELEASE/versionrelativePath/ !-- lookup parent from repository --/parentmodelVersion4.0.0/modelVersionartifactIdlab-24-apidoc-swagger/artifactIddependencies!-- 实现对 Spring MVC 的自动化配置 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- 引入 Swagger 依赖 --dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version/dependency!-- 引入 Swagger UI 依赖以实现 API 接口的 UI 界面 --dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependency/dependencies/project具体每个依赖的作用胖友自己认真看下艿艿添加的所有注释噢。
2.2 SwaggerConfiguration
因为 Spring Boot 暂未提供 Swagger 内置的支持所以我们需要自己定义配置类。
在 cn.iocoder.springboot.lab24.apidoc.config 包路径下创建 SwaggerConfiguration 配置类用于配置 Swagger 。代码如下
// SwaggerConfiguration.javaConfiguration
EnableSwagger2 // 标记项目启用 Swagger API 接口文档
public class SwaggerConfiguration {Beanpublic Docket createRestApi() {// 创建 Docket 对象return new Docket(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 信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title(测试接口文档示例).description(我是一段描述).version(1.0.0) // 版本号.contact(new Contact(芋艿, http://www.iocoder.cn, zhijiantianyagmail.com)) // 联系人.build();}}在类上添加 EnableSwagger2 注解 标记项目启用 Swagger API 接口文档。 通过 #createRestApi() 方法创建 Swagger Docket Bean 。每个属性的作用胖友看看艿艿的注释。大多数情况下胖友使用这些属性是足够的。不过如果想看看其它配置胖友可以自己去如下两个类翻翻 Docket.java ApiInfo.java
2.3 Application
创建 Application.java 类配置 SpringBootApplication 注解即可。代码如下
// Application.javaSpringBootApplication
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}}先暂时不启动项目。等我们添加好 Controller 。
2.4 UserController
在 cn.iocoder.springboot.lab24.apidoc.controller 包路径下创建 UserController 类提供用户 API 接口。代码如下
// UserController.javaRestController
RequestMapping(/users)
Api(tags 用户 API 接口)
public class UserController {GetMapping(/list)ApiOperation(value 查询用户列表, notes 目前仅仅是作为测试所以返回用户全列表)public ListUserVO list() {// 查询列表ListUserVO result new ArrayList();result.add(new UserVO().setId(1).setUsername(yudaoyuanma));result.add(new UserVO().setId(2).setUsername(woshiyutou));result.add(new UserVO().setId(3).setUsername(chifanshuijiao));// 返回列表return result;}GetMapping(/get)ApiOperation(获得指定用户编号的用户)ApiImplicitParam(name id, value 用户编号, paramType query, dataTypeClass Integer.class, required true, example 1024)public UserVO get(RequestParam(id) Integer id) {// 查询并返回用户return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());}PostMapping(add)ApiOperation(添加用户)public Integer add(UserAddDTO addDTO) {// 插入用户记录返回编号Integer returnId UUID.randomUUID().hashCode();// 返回用户编号return returnId;}PostMapping(/update)ApiOperation(更新指定用户编号的用户)public Boolean update(UserUpdateDTO updateDTO) {// 更新用户记录Boolean success true;// 返回更新是否成功return success;}PostMapping(/delete)ApiOperation(value 删除指定用户编号的用户)ApiImplicitParam(name id, value 用户编号, paramType query, dataTypeClass Integer.class, required true, example 1024)public Boolean delete(RequestParam(id) Integer id) {// 删除用户记录Boolean success false;// 返回是否更新成功return success;}}相比我们之前使用 SpringMVC 来说我们在类和接口上额外增加了 Swagger 提供的注解。 从使用习惯上我比较喜欢先添加 SpringMVC 的注解再添加 Swagger 的注解。 因为已经使用了 Swagger 的注解所以类和方法上的注释一般可以删除了除非有特殊诉求。 其中涉及到的 POJO 类有 UserAddDTO、UserUpdateDTO、UserVO 。
执行 Application 启动项目。然后浏览器访问 http://127.0.0.1:8080/swagger-ui.html 地址就可以看到 Swagger 生成的 API 接口文档。如下图所示
至此我们已经完成了 Swagger 的快速入门。不过考虑到胖友能够更好的使用我们来一个一个注解了解。
2.5 注解
在 swagger-annotations 库中在 io.swagger.annotations 包路径下提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的大多数场景下只需要使用到我们在 「2.4 UserController」 中用到的注解。
2.5.1 Api
Api 注解添加在 Controller 类上标记它作为 Swagger 文档资源。
示例如下
// UserController.javaRestController
RequestMapping(/users)
Api(tags 用户 API 接口)
public class UserController {// ... 省略
}效果如下 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.javaGetMapping(/list)
ApiOperation(value 查询用户列表, notes 目前仅仅是作为测试所以返回用户全列表)
public ListUserVO list() {// 查询列表ListUserVO result new ArrayList();result.add(new UserVO().setId(1).setUsername(yudaoyuanma));result.add(new UserVO().setId(2).setUsername(woshiyutou));result.add(new UserVO().setId(3).setUsername(chifanshuijiao));// 返回列表return result;
}效果如下 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.javaPostMapping(/delete)
ApiOperation(value 删除指定用户编号的用户)
ApiImplicitParam(name id, value 用户编号, paramType query, dataTypeClass Integer.class, required true, example 1024)
public Boolean delete(RequestParam(id) Integer id) {// 删除用户记录Boolean success false;// 返回是否更新成功return success;
}效果如下 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.javaApiModel(用户 VO)
public class UserVO {// ... 省略}效果如下
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 specified
2.5.5 ApiModelProperty
ApiModelProperty 注解添加在 Model 类的成员变量上声明每个成员变量的信息。
示例如下
// UserVO.javaApiModel(用户 VO)
public class UserVO {ApiModelProperty(value 用户编号, required true, example 1024)private Integer id;ApiModelProperty(value 账号, required true, example yudaoyuanma)private String username;// ... 省略 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 的 UI 界面上提供了简单的测试接口的工具。我们仅仅需要点开某个接口点击「Try it out」按钮。如下图
然后点击「Execute」按钮即可执行一次 API 接口的调用。如下图
在三个红圈中我们可以看到 Swagger 给我们提供了 提供了 curl 命令让我们可以直接在命令行执行。 提供了 Request URL 地址方便我们在浏览器中访问。 提供了执行结果我们可以人肉看看是否符合我们希望的结果。 当然实际项目开发中艿艿还是喜欢 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 文件中修改相关依赖。
?xml version1.0 encodingUTF-8?
project xmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsdparentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion2.1.3.RELEASE/versionrelativePath/ !-- lookup parent from repository --/parentmodelVersion4.0.0/modelVersionartifactIdlab-24-apidoc-swagger-knife4j/artifactIddependencies!-- 实现对 Spring MVC 的自动化配置 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- 1. swagger-bootstrap-ui 目前改名为 knife4j --!-- 2. 实现 swagger-bootstrap-ui 的自动化配置 --!-- 3. 因为 knife4j-spring 已经引入 Swagger 依赖所以无需重复引入 --dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring/artifactIdversion1.9.6/version/dependencydependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-ui/artifactIdversion1.9.6/version/dependency/dependencies/project具体每个依赖的作用胖友自己认真看下艿艿添加的所有注释噢。
3.2 界面一览
直接使用 Application 启动项目无需做其它任何的变更方便的说。
浏览器访问 http://localhost:8080/doc.html 地址就可以看到 新的 Swagger 生成的 API 接口文档。 注意下界面上艿艿添加的红圈和红字噢。更多功能胖友自己看 官方文档 哟。非常推荐生产中使用它嘿嘿。
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 YApi 是高效、易用、功能强大的 api 管理平台旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 APIYApi 还为用户提供了优秀的交互体验开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。 基于 Json5 和 Mockjs 定义接口返回数据的结构和文档效率提升多倍 扁平化权限设计即保证了大型企业级项目的管理又保证了易用性 类似 postman 的接口调试 自动化测试, 支持对 Response 断言 MockServer 除支持普通的随机 mock 外还增加了 Mock 期望功能根据设置的请求过滤规则返回期望数据 支持 postman, har, swagger 数据导入 免费开源内网部署信息再也不怕泄露了 胖友可以访问 http://yapi.demo.qunar.com/ 地址快速体验下 Yapi 的功能。
下面我们就一起来搭建一个 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 工具部署 YApi 平台是非常容易的。执行 yapi server 启动可视化部署程序输入相应的配置和点击开始部署就能完成整个网站的部署。部署完成之后可按照提示信息执行 node/{网站路径/server/app.js} 启动服务器。在浏览器打开指定 url, 点击登录输入您刚才设置的管理员邮箱默认密码为 ymfe.org 登录系统默认密码可在个人中心修改。 # 安装 yapi-cli 工具
$ npm install -g yapi-cli --registry https://registry.npm.taobao.org# 启动 YApi 平台部署工具
$ yapi server
在浏览器打开 http://0.0.0.0:9090 访问。非本地服务器请将 0.0.0.0 替换成指定的域名或ip4.4 YApi 平台部署
在浏览器打开 http://127.0.0.1:9090 地址设置 YApi 平台部署的信息。如下图
点击「开始部署」按钮会弹出“部署日志”窗口。如下图
耐心等待直到出现日志如下
初始化管理员账号成功,账号名zhijiantianyagmail.com密码ymfe.org
部署成功请切换到部署目录输入 node vendors/server/app.js 指令启动服务器, 然后在浏览器打开 http://127.0.0.1:3000 访问此时我们可以在命令行执行 ctrl-c 操作关闭YApi 平台部署工具。
4.5 YApi 平台启动
在命令行中执行如下命令启动 YApi 平台。
# 进入 yapi 部署路径
$ cd /Users/yunai/my-yapi/# 启动 yapi 平台
$ node vendors/server/app.js
log: -------------------------------------swaggerSyncUtils constructor-----------------------------------------------
log: 服务已启动请打开下面链接访问:
http://127.0.0.1:3000/
log: mongodb load success...项目启动完成。如果真正开始使用时建议使用 pm2 方便服务管理维护。命令如下
npm install pm2 -g // 安装pm2
cd {项目目录}
pm2 start vendors/server/app.js --name yapi // pm2管理yapi服务
pm2 info yapi // 查看服务信息
pm2 stop yapi // 停止服务
pm2 restart yapi // 重启服务这里我们可以先略过这个操作继续往下看。毕竟咱现在的重心是先入门。
4.5 创建项目
浏览器打开 http://127.0.0.1:3000/ 地址输入账号密码登陆。 登陆账号就是管理员邮箱。例如说艿艿这里使用的是 zhijiantianyagmail.com 登陆密码默认使用 ymfe.org 。
登陆成功后自动跳转到主界面点击右边的「添加项目」按钮进入「新建项目」的界面(http://127.0.0.1:3000/add-project) 。如下图 点击下方的「创建项目」按钮完成项目的创建。创建成功后我们会自动动跳转到刚才创建的项目下。如下图
4.6 设置 Swagger 自动同步
点击「设置」栏目然后选择「Swagger自动同步」栏目设置 Swagger 自动同步信息。如下图 友情提示Swagger 默认会自动暴露 项目地址/v2/api-docs 接口提供 Swagger 根据注解自动生成的 API 接口信息。胖友可以手动请求下该接口感受下。 实际上无论是 Swagger UI 也是基于该接口获得 API 接口信息。 点击「保存」按钮。成功后点击「接口」栏目就可以看到自动同步到的接口信息。如下图
至此我们已经完成搭建 YApi 平台并自动采集 Swagger 提供的 API 接口信息。YApi 的功能非常强大一定要翻一翻 官方文档 哟。例如说数据 Mock、高级 Mock 、自动化测试等等功能都是非常值得在项目中实践使用。
666. 彩蛋
那么在有了 API 接口文档之后如何和前端更好的沟通呢
一般来说每一个版本的需求产品都会提供 Axure 文档。后端开发在设计完接口之后可以考虑在每个界面上标记上使用到的接口的文档地址。注意是接口的文档地址啊例如说登陆界面需要使用到登陆接口那么我们可以把登陆接口对应的文档地址 http://127.0.0.1:3000/project/14/interface/api/11 标记到这个界面的原型上。
当然做标记的原则是需要跟产品协商好可以用来标记的区域不能影响到他们的工作。例如说 友情提示Axure 也是支持 团队协作 的噢。如果胖友家的产品还没使用批评怒喷一下他们。 这样在原型上标记好接口之后我们就可以找前端妹子对着原型顺着接口走一遍流程。如果走的很顺畅说明咱的接口棒棒的。嘿嘿~
一定要记住工具仅仅是工具一定要尽早达成前后端的一致。 下面进入话痨艿艿的碎碎念环节分享下艿艿在 API 接口文档的心路历程。
艿艿最早是在 2010 年的时候接触到前后端分离的架构。当时前端使用 ActionScript 后端使用 Servlet JDBC 通过 JSON 数据格式做交互开发一款 QQ 农场的网页游戏。 嘿嘿不要嫌弃 Servlet JDBC 很搓当时才学 Java 3 个月左右。那时候吧一个前端 两个后端人少直接 QQ 上发 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 了结束今天的哔哔迎接明天的哔哔。
