研发团队如何写好API接口文档
导读
- 背景
- 痛点在哪?
- 为什么要写接口文档?
- API规范
- 接口工具
- 总结
背景
随着业务的发展,支撑组的项目也是越来越多。同时,从整个支撑组项目架构体系(含运维和运营体系),我们对系统业务水平拆分,垂直分层,让业务系统更加清晰,产生了一系列平台和子系统,并使用接口进行数据交互。伴随着业务的发展,接口营运而生,并且会越来越多。
痛点在哪
我们运营和维护着诸多的对外接口,很多现有的接口服务寄宿在各个不同的项目,哪些应用在使用api也没有管理起来。并且以前的调用模式也是比较复杂,排错困难。
工作中也有合作开发的同事多次强力要求给出api文档,特别是每个开发组都来要一次,往往解释半天,大家也很痛苦。那么,让不开的问题是,如何管理和维护这些api,才能让大家都轻松?
- 没有接口文档
- 接口在代码里,只能看代码
- 没有集中的的api项目
- 相同业务的api分散在不同的项目
- 查找困难
- 代码和文档不匹配
- 代码接口更新,文档不更新
- 文档不规范
- 有的是word,有的是excel,有的是txt等等
- api不规范
- 命名,参数不规范
撸码一分钟,对接三小时
为什么要写接口文档?
- 项目开发过程中服务端和客户端工程师有一个统一的文件进行沟通交流开发
- 项目维护中或者项目人员更迭,方便后期人员查看、维护
API规范
- 接口名称
- 这里统一使用小写 如:api/order/get
- 可参考跟着Github学习Restful HTTP API 设计
- uri
- 提供客户端使用的全路径
- 如http://172.16.0.194:8057/api/order/get
- 请求协议
- Http,Https
- 请求方式
- POST,GET等
- 头部(系统参数)
- 加密签名,时间戳等
- 请求参数(业务)
- 业务相关的输入参数
- 响应参数(业务)
- 输出参数
返回示例
定义返货结果数据结构,更直观
- 1.返回成功
- 2.返回失败
接口工具
- eolinker
- 以后都使用该工具作为api归档
- 目前已经归档的项目
目前已经归档的项目api
总结
项目中使用restfulapi的情况较多,webservice,wcf,webapi均支持,所以这里该规范重点针对resfulapi。
有了规范更能减少沟通误差,提高工作效率
研发团队如何写好API接口文档的更多相关文章
- Swagger解决你手写API接口文档的痛
首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛 苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...
- Api接口文档管理工具,你知道哪些呢?
上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...
- Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...
- SpringBoot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...
- api(接口)文档管理工具
api(接口)文档管理工具 欢迎光临:博之阅API管理平台 ,做为一个app开发者,还没有用到api管理工具,你就OUT了 点击进入:程序员精华博客大全
- 智表ZCELL产品V1.4.0开发API接口文档 与 产品功能清单
为了方便大家使用ZCELL,应网友要求,整理编写了相关文档,现与产品一起同步发布,供大家下载使用,使用过程中如有疑问,请与我QQ联系. 智表(ZCELL)V1.4.0版本 功能清单文档下载地址: 功 ...
- Eolinker API 接口文档神器
Eolinker API 接口文档神器 群里小伙伴推荐的,还没有去研究,先记下来. API文档管理.自动化测试.开发协作利器 正在为数万企业管理超过100万APIs,提高开发效率以及规范开发流程
- “小葵日记”API接口文档
"小葵日记"项目API接口文档 时间:2017/10/31 (1)用户登录[待完成] POST:127.0.0.1/index/user/login data 数据别称 数据名 数 ...
- 构建标准OpenStack API接口文档
1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...
随机推荐
- scala Actor Akka
推荐博客:过往记忆 https://www.iteblog.com/archives/1154.html akka.io
- MVC是什么
MVC全名是Model View Controller,是模型(model)-视图(view)-控制器(controller)的缩写,一种软件设计典范,用一种业务逻辑.数据.界面显示分离的方法组织代码 ...
- create-react-app创建的项目中registerServiceWorker.js文件的作用
使用React官方的脚手架工具create-react-app创建的项目,目录中会存在registerServiceWorker.js这个文件,这个文件的作用是什么呢? 这个文件可以使用也可以不使用, ...
- 【RL-TCPnet网络教程】第14章 RL-TCPnet之TCP客户端
第14章 RL-TCPnet之TCP客户端 本章节为大家讲解RL-TCPnet的TCP客户端实现,学习本章节前,务必要优先学习第12章TCP传输控制协议基础知识.有了这些基础知识之后,再搞本 ...
- 高级Java面试总结2
1. JVM结构原理.GC工作机制详解 答:具体参照:JVM结构.GC工作机制详解 ,说到GC,记住两点:1.GC是负责回收所有无任何引用对象的内存空间. 注意:垃圾回收回收的是无任何引用的对 ...
- linux 完全关闭tomcat
由于直接调用tomcat的 shutdown.sh 有时无法完全关闭掉tomcat,使用 ps -ef | grep tomcat 查找发现tomcat依然还存在,并未完全关掉.在 catalina. ...
- [Java]LeetCode690. 员工的重要性 | Employee Importance
You are given a data structure of employee information, which includes the employee's unique id, his ...
- [Swift]LeetCode902. 最大为 N 的数字组合 | Numbers At Most N Given Digit Set
We have a sorted set of digits D, a non-empty subset of {'1','2','3','4','5','6','7','8','9'}. (Not ...
- [Swift]LeetCode928. 尽量减少恶意软件的传播 II | Minimize Malware Spread II
(This problem is the same as Minimize Malware Spread, with the differences bolded.) In a network of ...
- C/C++数据在内存中的存储方式
目录 1 内存地址 2 内存空间 在学习C/C++编程语言时,免不了和内存打交道,在计算机中,我们存储有电影,文档,音乐等数据,这些数据在内存中是以什么形式存储的呢?下面做一下简单介绍. 本文是学 ...