api文档编写好像很简单,其实不是。
一个良好的api文档,需要就有以下内容:
接口详细描述,接口参数详细描述,接口返回结果详细描述,容易理解的范例。这些内容其实是不少的,编写过程中还非常单调乏味。再加上项目紧张,积压的未编写api文档太多等等因素,造成了现实工作中,大部分api文档都是残缺不全的状况。从结果上看,编写api文档并不简单。

api文档编写好像只是后端工程师一个人的事情,其实不应该是。
实际工作中,api文档都是由实现这个api的后端工程师根据api来编写的。因为api是某人开发的,他知道最清楚,api文档就应该是这个人来写。大家都是这么理所当然的认为。但是这个接口不是后端工程师无中生有自己造出来的,而是大家根据需求讨论确定的。这个接口的功能、请求参数、返回结果,都是根据需求来确定的。不止和后端工程师关系密切,和产品人员、经理、前端人员都有关系,后来者也要根据这些api文档来工作。因此api文档编写不只是后端工程师一个人的事情。

api文档不要一个人完成,这样他的负担会很重,尤其是后端开发人员。我们应该是这样做:产品新建接口,填写部分内容,主要是接口名称和描述;后端开发人员编写接口的url、接口参数和返回字段;前端人员参与确定和编写部分api文档内容;技术经理从全局角度审查和编写部分api文档。

api文档应该尽早编写。
api文档是前后端开发人员协作的依据。没有api文档,前端开发人员就无法进行开发,项目也就无法推进。
传统的做法是:大家一起开需求会;开完需求会议后,后端开发人员花一段时间实现接口;为了让前端人员能尽快使用接口,后端开发人员会尽快简单编写一下api文档,再通知前端开发;前端开发人员再按照api文档开发程序,绑定数据;最后前后端人员一起联调。
这样单向的,一步一步依次执行的工作模式,像链条一节连着一节。即使其中某一个人工作高效,完成迅速,也难以加快项目整体的进度;相反,只要其中一个环节卡住了,整个项目也就停止了,上线变成不可能。总的结果是,让项目难以快速完成,上线时间非常紧张。
参与项目开发的所有都感觉到了这一模式的缺陷。

我们应该以api文档为中心展开工作。
首先,需要改进工序。
一,产品人员在调研需求,完成原型之后,应该整理一下每个页面,每个功能大概需要哪些接口,新建api文档,填写部分内容,包括接口名称,接口描述,返回的结果字段描述。
二,召集所有人员参加需求会,讲解需求,分配模块开发人员,讨论接口文档中哪些可以当场确定。
三,负责相同模块的前后端人员一起讨论,根据已经创建的api文档,确定api的url,请求参数名称,返回结果字段名称,完善好api文档;api文档的所有内容都应该完全确定,如果有疑问,应该找产品人员和经理一起确定。
四,前后端人员严格依照api文档各自开发,如果开发过程中有变动,一定要通知对方,并且修改api文档。这样两人同时进行开发,实现了并行工作,比老的api和文档完成后再做前端节约了大量时间。
五,前后端人员实现功能后进行联调,如果出现分歧,应该以api文档为基准。

以api文档为中心,尽快确定api文档和详细参数及结果,尽早完善文档,还有利于新人接收。新接手人参照完善的api文档,可以更快的熟悉项目,尽早完成任务。

以api文档为中心--前后端分开发离新思维的更多相关文章

  1. SpringBoot集成Swagger(Swagger的使用),生成接口文档,方便前后端分离开发

    首先上一张成果图.  1.Maven依赖 <dependency> <groupId>io.springfox</groupId> <artifactId&g ...

  2. 基于数据库的代码自动生成工具,生成JavaBean、生成数据库文档、生成前后端代码等(v6.0.0版)

    TableGo v6.0.0 版震撼发布,此次版本更新如下: 1.UI界面大改版,组件大调整,提升界面功能的可扩展性. 2.新增BeautyEye主题,界面更加清新美观,也可以通过配置切换到原生Jav ...

  3. 必应地图api文档,微软必应地图web开发版详解,可以在国内使用国外地图

    最近,公司项目要求在页面中嵌入地图,需求还算简单,但是由于必须具备响应式(主要是pc和移动端),而且由于公司业务是全球性的,要支持国外地点搜索.考虑到百度,腾讯,高德等等国内地图无法显示国外数据,谷歌 ...

  4. springboot 集成 swagger 自动生成API文档

    Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...

  5. 开源的API文档工具框架——Swagger简介

    初次接触Swagger是在2017年5月,当时公司正好要对整套系统架构进行重新设计,有同事推荐用这个技术框架来规范后台接口的API文档.当时因为架构重构,涉及改造的技术点太多,一时也就没太多精力,把S ...

  6. .Net Core3.0 WebApi 项目框架搭建 二:API 文档神器 Swagger

    .Net Core3.0 WebApi 项目框架搭建:目录 为什么使用Swagger 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.后端分离的形态,而且前端技术和后端技 ...

  7. 有了Swagger2,再也不用为写Api文档头疼了

    1.为什么要写Api文档 现在,前后端分离的开发模式已经非常流行,后端开发工程师只负责完成后端接口,前端页面的开发和渲染完全由前端工程师完成. 问题来了,前端工程师怎么知道后端接口的具体定义呢?答案是 ...

  8. springboot~mockMvc和asciidoctor生成基于TDD的API文档

    API文档是前端与后端快速开发,减少沟通成本的必要条件,有一份完善的文档是很必要的,由通过测试来生成文档的好处就是:测试数据有了,测试返回结果有了,而且可以对这些字段进行说明,很清晰,在springb ...

  9. Node与apidoc的邂逅——NodeJS Restful 的API文档生成

    作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...

随机推荐

  1. java实现人民币金额大写

    在与财务相关的应用中,经常会用到人民币金额的大写,比如发票的打印程序. 本题的任务是:从键盘输入一个十亿以内的正整数(int类型),把它转换为人民币金额大写(不考虑用户输入错误的情况). 比如,用户输 ...

  2. Java实现花朵数

    一个N位的十进制正整数,如果它的每个位上的数字的N次方的和等于这个数本身,则称其为花朵数. 例如: 当N=3时,153就满足条件,因为 1^3 + 5^3 + 3^3 = 153,这样的数字也被称为水 ...

  3. java实现第五届蓝桥杯李白打酒

    李白打酒 题目描述 话说大诗人李白,一生好饮.幸好他从不开车. 一天,他提着酒壶,从家里出来,酒壶中有酒2斗.他边走边唱: 无事街上走,提壶去打酒. 逢店加一倍,遇花喝一斗. 这一路上,他一共遇到店5 ...

  4. MySQL 8.0 yum安装和配置

    MySQL 8.0 centos7.5 x86_64 一.yum安装 1.先卸载机器和mysql有关的东西,有的安装了mariab-lib,会对安装有干扰,卸载了它. [root@localhost ...

  5. jQuery实现打飞机游戏

    玩法介绍:不同样式的飞机出来其它飞机会暂停飞行且处于无敌状态,子弹对它无效,你操纵的飞机不能碰到任何飞机,发出的子弹可以攻击正在飞行的飞机,每击落一架飞机会记录分数,你操纵的飞机碰到其它飞机即为游戏结 ...

  6. Unit1-窝窝初体验

    全文共3179字,推荐阅读时间10~15分钟. 文章共分四个部分: 作业分析 评测相关 重构策略 初体验感受 作业分析 第一次作业 第一次作业要求我们实现一个简单的幂函数求导工具,没有乘积和复合的情况 ...

  7. iOS-键盘弹出或隐藏时调整输入框的位置

    要达到自动调整的目标需要监听 keyboardWillShowNotification 跟 keyboardWillHideNotification, 同时需要实现点击其它地方时,通知隐藏键盘的事件 ...

  8. 有a1,a2,a3,a4,四个数组,四个数组重新组合成一个数组(A),间隔是10个元素

    好久没折腾Py了,这是去年年初2019.3月发在Q中的一个记录,因不从事这个,并且被在工厂耽误10几年,所以很少写Blog在这里,感觉这里比较正式,而在Q中只是随意性的记载, 但发布图片总是需要另外再 ...

  9. 从字符串到常量池,一文看懂String类设计

    从一道面试题开始 看到这个标题,你肯定以为我又要讲这道面试题了 // 这行代码创建了几个对象? String s3 = new String("1"); 是的,没错,我确实要从这里 ...

  10. 果然学习好是有道理的,学习Mysql与正则表达式笔记

    正则表达式是用来匹配文本的特殊的字符集合,将一个正则表达式与文本串进行比较,Mysql中用where子句提供支持,正则表达式关键字:regexp1.使用‘|’匹配两个串中的一个 2.使用‘[]’匹配几 ...