精华内容
下载资源
问答
  • 二、为什么要写接口文档?1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发2、项目维护中或者项目人员更迭,方便后期人员查看、维护三、接口规范是什么?首先接口分为四部分:方法、uri、请求参数、...

    一、什么是接口文档?
    在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。

    二、为什么要写接口文档?
    1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发
    2、项目维护中或者项目人员更迭,方便后期人员查看、维护

    三、接口规范是什么?
    首先接口分为四部分:方法、uri、请求参数、返回参数
    1、方法:新增(post) 修改(put) 删除(delete) 获取(get)
    2、uri:以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾;url参数就不说了。
    3、请求参数和返回参数,都分为5列:字段、说明、类型、备注、是否必填
    字段是类的属性;说明是中文释义;类型是属性类型,只有String、Number、Object、Array四种类型;备注是一些解释,或者可以写一下例子,比如负责json结构的情况,最好写上例子,好让前端能更好理解;是否必填是字段的是否必填。
    4、返回参数结构有几种情况:1、如果只返回接口调用成功还是失败(如新增、删除、修改等),则只有一个结构体:code和message两个参数;2、如果要返回某些参数,则有两个结构体:1是code/mesage/data,2是data里写返回的参数,data是object类型;3、如果要返回列表,那么有三个结构体,1是code/mesage/data,data是object,里面放置page/size/total/totalPage/list 5个参数,其中list是Arrary类型,list里放object,object里是具体的参数。

    注意:uri地址里不允许出现大写字母,如果是两个单词拼接,用/分开


    参考链接:https://www.zhihu.com/question/52409287/answer/130390641

    展开全文
  • 接口文档要如何

    万次阅读 多人点赞 2015-04-21 14:36:11
    一个简单的接口文档完给组长看后,发现漏洞百出。下面总结一下文档需要注意事项: 封皮 封面最好是本公司规定的封面,有logo,内容标题,版本号,公司名称,文档产生日期。(错误地方在于,文档的标题要和页眉...


            一个简单的接口文档,写完给组长看后,发现漏洞百出。下面总结一下写文档需要注意事项:

           封皮

           封面最好是本公司规定的封面,有logo,内容标题,版本号,公司名称,文档产生日期。(错误地方在于,文档的标题要和页眉中的标题一致)

           修订历史

           表格形式较好些。包括,版本,修订说明,修订日期,修订人,审核时间审核人。(我错误的地方在于,表格中其他空白表格没有居中)

           接口信息

           接口调用方式,是post方式还是get方式,接口地址,别人需要线上的哪个地址就写哪个。(自己提前测试好线上的这个接口,是否有其他问题,千万别犯低级的错误,尤其是某个字母写错)

           功能描述

           一定要清晰的描述接口功能。(不要遗漏一些细节,比如接口获取的信息不包括哪些哪些要写明白)

           接口参数说明

           每个参数都要和实际中调用的一样,包括大小写;参数的含义言简意赅的说明;格式,是string 还是int 还是long等格式(例如参数为@RequestParam("appKey") String appKey, @RequestParam("randomId") Integer randomId);说明部分,说明参数值是需要哪个公司提供,并详细说明参数怎么生成的,例如时间戳,是哪个时间段的;参数是否必填,一些参数是必须要有的,有些是可选参数,一定要注意写清晰。

           返回值说明

           1、有一个模板返回值,并说明每个返回参数的意义。

           2、提供一个真实的调用接口,真实的返回值。


           接口调用限制,接口调用安全方面

           为了接口安全,我们可以进行md5加密方式,或者自己公司一个特殊的加密过程,只要双方采用一致的加密算法就可以调用接口,保证了接口调用的安全性。

           文档全局方面

           文档大标题的字体字号一致,小的分标题一致,正文部分字号也要一致。文章整体字的类别一致,我认为微软雅黑字体样式给人感觉比较清晰。文档目录,自动生成的目录会添加些许的修饰,去掉不整齐的部分,得到一个整齐的目录格式。

           文档维护

           文档在维护的时候,如有修改一定要写上修改日期,修改人,对大的修改要有版本号变更。

           好文档标准检验

           我认为检验一个文档写的是否好,主要还是在内容方面,内容是否仔细没有疏漏之处。是否发给别人使用的时候,无需沟通就能把接口调通。别人通过成功的把接口调通,这就是一个好文档。

           总结

           虽然对于敏捷开发来说项目不需要需求,设计,详细设计等文档,但是在和别的公司在调用接口的时候,是一定要总结成文档的,形成接口规范,文档规范。昨天看到微信分享的一篇文档,叫做《教养,就是让别人舒服》,我想在写文档的时候,把自己当做看文档的人,怎么写让别人舒服,我想这就是写文档的“教养”吧。

           菜鸟欢迎您能共同讨论~




    展开全文
  • 正确规范写接口文档

    万次阅读 多人点赞 2018-05-17 14:14:27
    前言 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。银联接口文档案例:5.2.2 统一收单线下交易查询...

    正确规范写接口文档


    前言

      正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。


    接口规范内容

    • 接口名称
    • 场景说明
    • 接口说明
    • 请求参数
    • 响应参数
    • 错误码

    参数内容

    字段名 
    变量名 
    是否必填 
    类型 
    示例值 
    描述

    错误码内容

    名称 
    描述 
    原因 
    解决方案


    一.银联接口文档示例 (适用于接口规范文件)

    5.2.2 统一收单线下交易查询

    5.2.2.1 场景说明

    收单机构可以通过该接口主动查询订单状态,完成下一步的业务逻辑。需要调用查询接口的情况:

    当收单机构后台、网络、服务器等出现异常,收单机构系统最终未接收到支付通知;调用支付接口后,返回系统错误或未知交易状态情况;调用alipay.trade.pay,返回INPROCESS的状态;调用alipay.trade.cancel之前,需确认支付状态。


    5.2.2.2 接口说明

    公共请求参数中的method填写alipay.trade.query。


    5.2.2.2.1 请求参数
    参数参数名类型是否必填最大长度描述示例值
    out_trade_no商户订单号String32订单支付时传入的商户订单号,和网联交易号不能同时为空。trade_no,out_trade_no如果同时存在优先取trade_no20150320010101001
    .....................
    trade_no网联交易号String64网联交易号,和商户订单号不能同时为空2014112611001004680073956707

    5.2.2.2.2 响应参数
    参数参数名类型是否必填最大长度描述示例值
    trade_no网联交易号String64网联交易号2013112011001000000121536
    .....................
    out_trade_no商户订单号String32商户订单号6823789339978240
    TradeFundBill字段说明:
    参数参数名类型是否必填最大长度描述示例值
    fund_channel资金渠道String32交易使用的资金渠道ALIPAYACCOUNT
    .....................

    5.2.2.3 错误码

    错误码错误描述原因解决方案
    SYSTEMERROR接口返回错误系统超时请不要更换商户退款单号,请使用相同 参数再次调用 API。
    NOTENOUGH余额不足商户可用退 款余额不足此状态代表退款申请失败,商户可根据 具体的错误 示做相应的处理。
    ............

    二.API开发接口文档示例 (适用于http、https 接口)

    3.1.1 查询排重接口

    3.1.1.1 场景说明

    查询信息是否已存在。


    3.1.1.2 接口详情

    3.1.2.1 接口地址
    接口详情 
    地址http://www.baidu.com (正式环境)
    请求方式GET

    3.1.2.2 参数
    参数是否必填说明
    idfa广告标识符
    .........
    source渠道来源,具体值在接入时再进行分配

    3.1.2.3 返回结果
    返回结果格式JSON
    状态码10000success(调用成功)
     ......
     10010access prohibited(访问拒绝)

    3.1.1.3 调取示例

    3.1.1.3.1 查询成功


    "state": 10000, 
    "message": "success", 
    "data": { 
    "BD239708-2874-417C-8292-7E335A537FAD": 1 //已经存在 



    "state": 10000, 
    "message": "success", 
    "data": { 
    "BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在 

    }


    3.1.1.3.2 接口调用失败


    "state": 10010, 
    "message": "access prohibited", 
    "data": [ 

    }


    展开全文
  • 没有接口文档,如何接口测试

    千次阅读 2019-03-19 10:42:10
    1、接口文档没有提及的一个查询的接口 文档没有提及根据手机号查询交易流水 2、WEB根据手机号查询交易流水 3.postman的接口测试 (1)路径url:postman的url和前端的url是一样的 (2)发送请求:post ...

    1、接口文档没有提及的一个查询的接口

    文档没有提及根据手机号查询交易流水

    2、WEB根据手机号查询交易流水

    3.写postman的接口测试

    (1)路径url:postman的url和前端的url是一样的

    (2)发送请求:post

    (3)请求头:a.Content-Type互联网媒体类型:application/json键-值”对的方式组织的数据

                            b.认证信息:Authorization 登录的时候获取http://**web.yidianche.net/pressure/132****(这个是专门用来获取                                      Authorization 认证信息的)     区别:http://***web.yidianche.net/performance132***(这个是前端直接登录,不                              需要扫描)

    (4)请求体body:raw方式,写成字符串的形式WEB和postman的数据也是一样的

    4、根据web上的搜索输入框,至少要写4个接口用例

    (1)手机号:

    data: "{"page":1,"rows":10,"orderNo":"","mobilePhone":"132**","payWater":"","startCreateTime":"","endCreateTime":""}"

    (2)购买订单

    data: "{"page":1,"rows":10,"orderNo":"UAT20190314095925004**","mobilePhone":"","payWater":"","startCreateTime":"","endCreateTime":""}"

    (3)微信单号

    data: "{"page":1,"rows":10,"orderNo":"","mobilePhone":"","payWater":"UAT2019031409592000522","startCreateTime":"","endCreateTime":""}"

    (4)交易时间

    {"data": {"page":1,"rows":10,"orderNo":"","mobilePhone":"","payWater":"","startCreateTime":"2019/03/14","endCreateTime":"2019/03/14"}}

    5.接口文档中一些非必须的参数,是提供查询时的选项

    展开全文
  • 我刚接触这行,人给了我一份接口文档,叫我接口,存进数据库之后之后用定时任务每分钟取一次.......这里说的接口到底是些个什么,是service还是dao,希望指导一下谢谢
  • 接口模板 接口文档

    千次下载 热门讨论 2016-05-20 16:54:01
    接口模板 接口文档
  • 如何正确规范写接口文档

    万次阅读 2018-03-15 15:50:37
     正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员的。一个工整的文档显得是非重要。下面我将我看到的一篇接口文档做一个总结 开始吧!!! 接口1: 查询排重接口 ...
  • 什么是接口文档?接口文档书写规范?

    千次阅读 2018-12-14 14:37:34
    在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。  接口文档分为四部分:请求方法type、请求...
  • 正确规范api接口文档

    千次阅读 2019-06-06 10:28:59
    正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员的。一个工整的文档显得是非重要。 接口1 查询排重接口: 接口详情 请求地址 /api/user/login/ 请求方式 GET ...
  • 接口文档定义

    千次阅读 2019-03-18 21:23:36
    二、为什么要写接口文档? 1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发 2、项目维护中或者项目人员更迭,方便后期人员查看、维护 三、接口规范是什么? 首先接口分为四部分:方法、uri、请求参...
  • 接口文档编辑工具+接口文档编写

    千次阅读 2020-03-05 19:12:03
    接口文档编辑工具 参考@Lucky锦【接口文档编辑工具】 Swagger: 通过固定格式的注释生成文档. 省时省力,不过有点学习成本。https://swagger.io/ eoLinkerhttps://www.eolinker.com/#/ ShowDoc(我使用的是这个,...
  • 写接口文档及生成mock数据

    千次阅读 2018-09-11 18:15:17
    写接口文档及生成mock数据 在web应用开发的过程中,与前端联调时总会有一些接口,需要接口文档,在接口先行的情况下,前端不能拿到实际的接口进行开发,所以就需要mock数据。 今天搜索了下,阿里在这方面已经有...
  • 接口文档

    千次阅读 2017-04-09 23:07:45
    二、为什么要写接口文档? 1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发 2、项目维护中或者项目人员更迭,方便后期人员查看、维护 三、接口规范是什么? 首先接口分为四部分:方法、uri、
  • 如何写接口文档

    千次阅读 2016-09-08 17:22:50
    最近项目进入二期,开始进行app接口的开发...跟着大神学习了如何写接口文档 Web API文档生成工具apidoc http://www.jianshu.com/p/bb5a4f5e588a 官方地址 http://apidocjs.com/ /** * 要闻 * * @author h
  • markdown来API接口文档

    千次阅读 2019-03-19 17:01:00
    XX项目API接口文档 文章目录XX项目API接口文档通用说明:①接口通用前缀:② 接口通用返回:1 登录模块1.1 各移动端登录通用接口模板源码如下 通用说明: ①接口通用前缀: 测试环境: ...
  • 类库说明文档生成工具,适合给API接口写说明文档
  • 用自己接口文档生成工具生成入参出参文档 下载 建工程 安装 附图用自己接口文档生成工具生成入参出参文档本文主要是演示这个工具是怎么用的下载建工程下载的文档是用eclipse直接打包的原工程,直接引到...
  • CRMEB接口文档

    千次阅读 2019-09-29 09:01:11
    CRMEBv3.0采用TP6框架,前后端完全分离...一下是部分接口文档,全部接口文档还得联系官方 地址:http://github.crmeb.net/u/lingting crmeb crmeb api 公共信息 CRMEB API接口说明 公共接口 活动状态 基本信息...
  • 提供一些我自己使用过的api数据接口,让学习前端的朋友可以提早熟练地调用一些Api...点击查看文档,就可以进入接口文档的详细使用步骤了。 这个接口很适合喜欢音乐的朋友去打造属于自己的音乐主页 第二个: 黑马...
  • laravel接口 接口文档

    千次阅读 多人点赞 2018-11-11 19:07:29
    接口 先在控制器里一个接口的方法 之所以了两个方法 因为写接口单独创建一个控制器比较好 避免与页面展示冲突 // 展示页面 配合城市接口执行 public function cityshow(){ $data = DB::table('jy_city')-&...
  • 移动端接口文档示例

    2016-08-25 09:43:52
    移动端接口文档示例
  • 接口规范说起来大,其实也就那么几个部分,接口规范、接口管理工具、接口文档编写、开发文档编写。以下将详细介绍,下面进入正文:接口规范文档具体内容如下:一:协议规范二:域名规范三:版本控制...
  • apidocphp接口文档

    千次阅读 2017-08-23 23:05:16
    1.apidoc需要node.js支持,需要安装node.js 2.通过npm安装apidoc  npm install apidoc -g ...4.在docs目录下,创建对应的具体接口信息 xxx.js,创建对应的模板文件apidoc.json(如果需要独立footer.md,header
  • Markdown写接口文档,自动添加TOC

    万次阅读 2016-03-18 20:14:47
    这回换Markdown来做接口文档好了。(不敢说代替Word,只能说个人感觉更为方便)当然,还要辅之以Git,来方便版本管理。 Markdown基本语法也没啥好说的,随便百度一下几分钟看懂基本的,20%的知识完成80%的任务嘛,...
  • 接口文档相关问题

    千次阅读 2019-11-01 16:45:28
    接口文档相关内容
  • Android 接口文档

    千次阅读 2016-12-28 14:42:15
    前言每个项目进行研发之前,都会有很多的相对应的文档,当然比较重要的一个就是接口文档,当然接口文档版本也有很多,这边只是把自己文档的一部分内容个示例记录一下,方便以后自己查看。当然大家有很好的建议和...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 531,647
精华内容 212,658
关键字:

一般接口文档是谁写