API生命周期第二阶段——设计:采用swagger进行API描述、设计
本篇博客主要是以swagger为依托,介绍API生命周期的第二个阶段——设计!在详细介绍之前,我必须声明一点:如果是想了解swagger和项目框架的集成的,这里没有。我要介绍的swagger进行的API描述,还处于API设计阶段,没有到第三阶段的实施呢(具体的分析,请看本篇博客第四部分:总结)。但如果你想了解各种集成,建议你直接百度,很多实例。
另外,本篇博客,没有具体的介绍swagger的定义,主要是从具体的开发现状中引出的这种工具去解决问题。 如果需要swagger的宏观定义说明,请参考:https://swagger.io/
一、一些场景
1,在开发的过程中,老是有人问你服务的地址。关于服务的调用地址,说了一遍又一遍。还有,关于参数的位置,类似于:“你这个参数是写在路径里的?”“你这个参数是写在URL请求参数里的?”“你这个参数到底是写在哪儿了?”“我期待的返回数据不是这样的!!!”“我要的返回值类型也不是这样的!!!”“这个返回码是什么意思来着???” 这样的问题,听第一遍的时候,心情很复杂,听多遍的时候,没有心情。
2,会专门用时间,前端工程师和后端工程师核对接口(得注意了,核对接口而已,并没有一个可视化的方式,告诉前端工程师每个接口的实操情况)。先不管本次核对是否高效并且有效,关键问题是:拿出了专用时间用于前后端工程师核对接口定义(还必须是本人到场确认)。
3,很多的接口文档,很多的接口描述规范,它们甚至不是一个入口。
4,接口被私自篡改,你不知道哪个接口正在使用,哪个接口已经成为过去式。当实施代码更更改之后,更恐怖的是,根本没来得及(我更愿意说是因为来不及)修改相应的接口文档。
5,API文档的版本控制(只是文档的版本)
6,接口的访问权限说明难以描述
7,前端等待后端实施结束,再次确认服务地址,前面的几个点开始循环了。。。。。。
8,9,10......
有没有其中一个,是你特别想干掉它的????? 有没有抱怨过:当时写代码之前又不说有问题,现在代码写完了又说不对,为什么当时不说清楚她们前端那伙人到底想要什么。
事实上第一点就已经让我崩溃了好几次!!!
二、API描述
接下来,主要是讲swagger editor!
关于API 有几个比较关键的概念:API描述、API发现、API档案 接下来咱们一个一个的解决问题:
总结起来以上一些场景(额,实话说,那就是我目前开发中所面对的。我们用了更多的时间去反复确认,甚至抱怨争吵一些本不应该的点。耗费了一次又一次的时间,却仍然没有得到一个有效的解决。当然,从之前的无接口文档——有文档无规范——有接口定义规范——在线规范文档—— 我们已经成长了很多),它们一个很大的根源在于两点:
1,语义规范的API描述:参数是否必需,参数位置,参数类型,请求路径,请求权限,请求协议,方法返回值,方法返回类型,状态码含义等等
2,可视化的API mock 测试:当我请求这个rest API接口时,它到底会返回什么?它究竟是不是我想要的???(注意了,因为需求变动而产生的API接口重定义,和因为沟通不清楚而导致的废弃再定义,这两个是不一样的概念)
那么,swagger可以帮我们做什么??先看一个宏观的思维导图吧:
往简单了说吧:1,规范的API定义
schemes:
- https
consumes:
- "application/json"
produces:
- "application/json"
paths:
/resources/api/tb-build:
post:
tags:
- "建筑"
description: "新增一个建筑"
operationId: "addBuild"
produces:
- "json"
parameters:
- in: "body"
name: "body"
description: "Pet object that needs to be added to the store"
required: true
schema:
$ref: "#/definitions/Build"
responses:
200:
description: "新增建筑成功!"
404:
description: "找不到API服务"
default:
description: "未知错误"
这是一段我刚写简单的API描述,关于这个接口的定义,有什么不清楚的没???额,具体内容都可以写中文哈,除了左侧的语义描述!更为详细的API描述,请参考:
http://editor.swagger.io/?_ga=2.123928330.1613166242.1502105842-171987874.1501570940#/
三, 可视化的API mock 测试
咱们现在看一下对于上述接口的mock测试:
在swagger的mock测试中,可以在线可视化立即测试所编写的API接口实操情况。
做mock service Test 的意义是什么??? 大家可以思考,尤其是这一步是在代码实施之前。 由于它是一个在线的可视化mock测试,前后端工程师可以不必在物理区域在一起。更由于swagger的API协作合并,当发现某一个API描述有问题时,某一方可以在组织下重建它所期待的描述,然后最终合并通知!
四、总结
对于swagger的使用阶段
swagger可不可以在代码实施的时候集成使用???
可以,但是,这需要确定快速构建部署,可快速修改! 明白什么意思没呢??? 试着考虑一下,开发了很久,才开发完,API的对应文档出炉,然后别人再根据文档调用????额,如果能在管理上让别人不闲着,好像也没什么要紧哈。 那我们来确认第二点,你老人家吭哧坑次开发了好久,文档也出来了,然而你提供的,根本不是别人想要的,呵 呵 哒!!!
其实,这一点也是我们后面会说到的第三阶段具体实施的三种不同模式的区别。 在实施之前运用swagger设计API,这是design -first,将swagger集成到代码实施,这是code -first,还有一种是API -first,具体的,咱们在第三阶段进行说明。
API生命周期第二阶段——设计:采用swagger进行API描述、设计的更多相关文章
- API生命周期第二阶段——设计:如何设计API(基于swagger进行说明)
题外话 在新的项目中,推行了swagger用于对API的设计.以期待解决我们上篇博客中说到了一些现象,提升工作效率.那么,结合到当时和全项目组成员做培训,以及后续的给主要应用者做培训,以及当初自己接触 ...
- Uber的API生命周期管理平台边缘网关(Edge Gateway)的设计实践
设计边缘网关(Edge Gateway),一个高可用和高可扩展的自助服务网关,用于配置.管理和监控 Uber 每个业务领域的 API. Uber 的 API 网关的演进 2014 年 10 月,优步开 ...
- java EE技术体系——CLF平台API开发注意事项(4)——API生命周期治理简单说明
文档说明 截止日期:20170905,作者:何红霞,联系方式:QQ1028335395.邮箱:hehongxia626@163.com 综述 有幸加入到javaEE技术体系的研究与开发,也得益于大家的 ...
- API生命周期
这一系列的文章,主要是结合了参加Oracle code之后对于API治理的记录收获,以及回到公司后,根据公司目前的一些现状,对此加以实践的过程总结 API生命周期通常包括八个内容,而安全策略贯穿始终. ...
- Uber三代API 生命周期管理平台实现 Uber
Uber三代API 生命周期管理平台实现 - InfoQ https://www.infoq.cn/article/H8Ml6L7vJGQz0efpWvyJ Uber 三代 API 生命周期管理平台实 ...
- Asp.net Mvc 与 Web Api生命周期对比
完整的生命周期比较复杂,对细节感兴趣的同学可购买老A的图书学习:传送门 本文只简单讲述路由注册.controller创建.action选择的3个主逻辑线,其他的内容大家可自己阅读相应的代码 先上二者单 ...
- API生命周期第三阶段:API实施模式,以及结合swagger和项目现状的最佳模式
这篇博客,主要是宏观介绍一下开发模式,尤其是针对于目前公司前后分离的项目! 一.API实施模式概述 API实施模式,主要是三个,其中API-First又是作为一种指导思想的一种,所以,简单来说事实实施 ...
- API生命周期第三阶段:API实施:使用swagger codegen生成可部署工程,择取一个作为mock service
在分享培训了swagger对于API的设计之后,有一些人问我说:你看,现在咱们前端使用web_API做为mock data在进行测试,后端也有mock 测试.然后我们再进行联调,这之中肯定会出现一些偏 ...
- 微服务手册:API接口9个生命节点,构建全生命周期管理
互联网应用架构:专注编程教学,架构,JAVA,Python,微服务,机器学习等领域,欢迎关注,一起学习. 对于API,在日常的工作中是接触最多的东西,特别是我们软件这一行,基本就是家常便饭了,在百度百 ...
随机推荐
- CAS 配置NLB 负载均衡网络无法连接
在虚拟机与虚拟机.虚拟机与实机之间利用Windows操作系统自带的网络负载均衡功能如选择单播集群模式,网络就无法通讯,NLB不成功. Scenario #1 在虚拟机与虚拟机之间选择多播模式NLB可正 ...
- SVN合并步骤
1.trunk->branch/tag 分支路径在分支文件夹中,选择右键检出 2.合并分支到主干分支新增 1.txt 文件 需要合并到主干 在trunck->鼠标右键合并->合并到不 ...
- C#中Image类与byte[]之间的转换
//将image转化为二进制 public byte[] GetByteImage(Image img) { byte[] bt = null; if (!img.Equals(null)) { us ...
- groups - 显示用户所在的组
总览 (SYNOPSIS) groups [OPTION]... [USERNAME]... 描述 (DESCRIPTION) --help 显示此帮助, 然后退出 --version 显示版本信息, ...
- Jquery二维码在线生成(不能生成图片文件)
附件地址:http://files.cnblogs.com/files/harxingxing/jQuery%E4%BA%8C%E7%BB%B4%E7%A0%81%E5%9C%A8%E7%BA%BF% ...
- Problem D: 小平查密码
Problem D: 小平查密码 Time Limit: 1 Sec Memory Limit: 128 MBSubmit: 194 Solved: 40[Submit][Status][Web ...
- Java基础 匿名内部类 异常 多线程 集合面试题
匿名内部类:没有名字的内部类.就是内部类的简化形式.一般只用一次就可以用这种形式.匿名内部类其实就是一个匿名子类对象.想要定义匿名内部类:需要前提,内部类必须继承一个类或者实现接口. 匿名内部类的格式 ...
- 如何用VS2017用C++语言写Hello world 程序?
1,首先,打开VS2017. 2,左上角按文件——新建——项目,或按ctrl+shift+n. 3,按照图片里的选,选完按“确定”. 4,右键“源文件”,再按添加——新建项. 5,剩下的就很简单了,只 ...
- C++ 学习笔记(三)string 类
在C语言中如果想要使用字符串那么有两种方法: 1.定义char型数组:char[10]; 然后将每个字符填充到对应的位置. 优点:这种方式将字符串放在内存所以每个位置都可以修改. 缺点:赋值比较麻烦, ...
- [JZOJ] 5837.Omeed
先摆出来这个式子 \[ score=A\sum S_i+B\sum S_i\times f(i) \] 先研究\(f\)函数(也就是Combo函数) 显然的有 \[ f(i)=P_i(f(i-1)+1 ...