本篇博客主要是以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描述、设计的更多相关文章

  1. API生命周期第二阶段——设计:如何设计API(基于swagger进行说明)

    题外话 在新的项目中,推行了swagger用于对API的设计.以期待解决我们上篇博客中说到了一些现象,提升工作效率.那么,结合到当时和全项目组成员做培训,以及后续的给主要应用者做培训,以及当初自己接触 ...

  2. Uber的API生命周期管理平台边缘网关(Edge Gateway)的设计实践

    设计边缘网关(Edge Gateway),一个高可用和高可扩展的自助服务网关,用于配置.管理和监控 Uber 每个业务领域的 API. Uber 的 API 网关的演进 2014 年 10 月,优步开 ...

  3. java EE技术体系——CLF平台API开发注意事项(4)——API生命周期治理简单说明

    文档说明 截止日期:20170905,作者:何红霞,联系方式:QQ1028335395.邮箱:hehongxia626@163.com 综述 有幸加入到javaEE技术体系的研究与开发,也得益于大家的 ...

  4. API生命周期

    这一系列的文章,主要是结合了参加Oracle code之后对于API治理的记录收获,以及回到公司后,根据公司目前的一些现状,对此加以实践的过程总结 API生命周期通常包括八个内容,而安全策略贯穿始终. ...

  5. Uber三代API 生命周期管理平台实现 Uber

    Uber三代API 生命周期管理平台实现 - InfoQ https://www.infoq.cn/article/H8Ml6L7vJGQz0efpWvyJ Uber 三代 API 生命周期管理平台实 ...

  6. Asp.net Mvc 与 Web Api生命周期对比

    完整的生命周期比较复杂,对细节感兴趣的同学可购买老A的图书学习:传送门 本文只简单讲述路由注册.controller创建.action选择的3个主逻辑线,其他的内容大家可自己阅读相应的代码 先上二者单 ...

  7. API生命周期第三阶段:API实施模式,以及结合swagger和项目现状的最佳模式

    这篇博客,主要是宏观介绍一下开发模式,尤其是针对于目前公司前后分离的项目! 一.API实施模式概述 API实施模式,主要是三个,其中API-First又是作为一种指导思想的一种,所以,简单来说事实实施 ...

  8. API生命周期第三阶段:API实施:使用swagger codegen生成可部署工程,择取一个作为mock service

    在分享培训了swagger对于API的设计之后,有一些人问我说:你看,现在咱们前端使用web_API做为mock data在进行测试,后端也有mock 测试.然后我们再进行联调,这之中肯定会出现一些偏 ...

  9. 微服务手册:API接口9个生命节点,构建全生命周期管理

    互联网应用架构:专注编程教学,架构,JAVA,Python,微服务,机器学习等领域,欢迎关注,一起学习. 对于API,在日常的工作中是接触最多的东西,特别是我们软件这一行,基本就是家常便饭了,在百度百 ...

随机推荐

  1. 微软Coco Blockchain Framework:一键解决企业级区块链三大难题

    近年来,异军突起的“区块链”受到全行业的广泛关注,众多企业级用户在积极拥抱新技术的过程中却面临三大难题:性能.隐私和组织管理.如果不能很好地解决这些“顽固分子”,区块链技术就相对局限,很难发挥出应有的 ...

  2. 用Python完成根据日期计算是星期几

    import datetime def week(year,month,day): someday=dayetime.date(year,month,day) result={ "0&quo ...

  3. Linux基础环境_安装配置教程(CentOS7.2 64、JDK1.8、Tomcat8)

    Linux基础环境_安装配置教程 (CentOS7.2 64.JDK1.8.Tomcat8) 安装包版本 1)     VMawre-workstation版本包 地址: https://my.vmw ...

  4. Cesium左右立体视觉续篇——遗留问题(渲染错误)以及临时替代方案

    遗留问题详细说明 已解决部分 立体视觉中的视差: 横向渲染压缩. 遗留问题 1.左右分屏中的部分地图切片未渲染 问题描述:如下图(图片为解决问题后的图片),红色区域会显示黑色,无法正常显示影像.2.相 ...

  5. 一个.java文件内只能写一个class吗

    先给结论:当然不是!! 可以有多个类,但只能有一个public的类,并且public的类名必须与文件名相一致.一个文件中可以不含public类,如果只有一个非public类,此时可以跟文件名不同. 为 ...

  6. 用dfs求解八皇后问题

    相信大家都已经很熟悉八皇后问题了,就是指:在8X8格的国际象棋上摆放八个皇后,使其不能互相攻击,即任意两个皇后都不能处于同一行.同一列或同一斜线上,问有多少种摆法.主要思路:按行进行深度优先搜索,在该 ...

  7. vue 文件流下载xlsx 功能实现

    downLoadFile (url, name) { this.xhr = new XMLHttpRequest() this.xhr.open('GET', url, true) this.xhr. ...

  8. MySql查询时间段的方法

    本文实例讲述了MySql查询时间段的方法.分享给大家供大家参考.具体方法如下: MySql查询时间段的方法未必人人都会,下面为您介绍两种MySql查询时间段的方法,供大家参考. MySql的时间字段有 ...

  9. 面向对象OO第一单元三次作业总结

    (一)第一单元的作业围绕着多项式的求导,从简单到复杂,主要的要求是 作业一:只有两种格式的因子:带符号整数(+02)和幂函数(x^+02). 作业二:在作业一的基础上添加了:sin(x)和cos(x) ...

  10. javaweb基础(22)_Servlet+JSP+JavaBean实战登陆

    一.Servlet+JSP+JavaBean开发模式(MVC)介绍 Servlet+JSP+JavaBean模式(MVC)适合开发复杂的web应用,在这种模式下,servlet负责处理用户请求,jsp ...