接口文档_接口文档示例 - CSDN
精华内容
参与话题
  • 一份完整的接口文档

    千次阅读 2019-11-22 10:51:41
    https://www.jianshu.com/p/c5b1828d0dc6
    展开全文
  • 接口文档模板

    千次阅读 2018-07-24 23:21:25
    接口调用请求说明http请求方式: GEThttp://127.0.0.1:8080/CrazyDormitory-Server/stu/userList.json?p=1&num=5 参数说明 参数 是否必须 说明 p 是 ...

    获取用户信息

    开发者通过指定页数、每页显示条数,获取用户信息。

    接口调用请求说明
    http请求方式: GET
    http://127.0.0.1:8080/CrazyDormitory-Server/stu/userList.json?p=1&num=5

    参数说明

    参数

    是否必须

    说明

    p

    指定页数

    num

    每页要显示的数量


    返回说明

    正常情况下,后台会返回下述格式JSON数据包:

     

    {

    "datas":[

    {

    "dormitory":"5栋",

    "id":12,

    "name":"彭珂",

    "phone":"15166668888",

    "school":"江西xxx大学",

    "sex":"男"

    }

    ]

    }

     

    参数说明

     

    参数

    说明

    dormitory

    宿舍

    id

    Id

    name

    姓名

     

     

    Phone

    联系方式

    School

    学校

    Sex

    性别


    没有查询到:

    {"datas":[]}

     

    >>>---------------------------------------------------<<<

    学习资料下载

    >>>---------------------------------------------------<<<

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

    万次阅读 多人点赞 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": [ 

    }


    展开全文
  • 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。 项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员...

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

    一、为什么要写接口文档?

    1. 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。
    2. 项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员更迭,方便后期人员查看、维护

    二、接口规范是什么?

    首先接口分为四部分:方法、uri、请求参数、返回参数

    1. 方法:新增(post) 修改(put) 删除(delete) 获取(get)

    2. 接口详情
      地址 www.baidu.com
      方式 GET
    3. uri:以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;
      中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾;url参数就不说了中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾;url参数就不说了

    4. 请求参数和返回参数,都分为5列:字段、说明、类型、备注、是否必填
      字段是类的属性;说明是中文释义;类型是属性类型,只有String、Number、Object、Array四种类型;
      备注是一些解释,或者可以写一下例子,比如负责json结构的情况,最好写上例子,好让前端能更好理解;是否必填是字段的是否必填。

    5. 返回参数结构有几种情况:

      1. 返回接口调用成功还是失败(如新增、删除、修改等),如下图:

        返回结果 格式 JSON
        状态码 200 success(成功)
        状态码 500 error(失败)
        状态码 501 param error(参数错误)
      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地址里不允许出现大写字母,如果是两个单词拼接,用/分开

    三.如何合理设计接口?

    一、 设计原理

    1. 深入了解需求:从“客户端-接口-数据库”的层次上看,接口明显扮演着承上启下的角色,一方面要明白接口要什么数据,另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求,你就无法正确抽象对象来组织数据给客户端,也无法验证数据库的数据结构能否满足需求。
    2. 了解数据库结构:既然接口要明白如何从数据库获取、组织数据,就当然要了解数据库结构啦。
    3. 了解客户端原型:了解原型,其实更多是为了帮助你设计接口时需要提供的数据和结构。

    二、设计原则

    1. 充分理由:不是随便一个功能就要有个接口,也不是随便一个需求就要加个接口。每新建一个接口,就要有充分的理由和考虑,无意义的接口不仅增加了维护的难度,更重要是对于程序的可控性的大大降低,接口也会十分臃肿。
    2. 职责明确:一个接口只负责一个业务功能,比如查询会员,但不要在查询会员的同时还有修改权限等类似的其他业务功能,应该分成两个接口做。
    3. 高内聚低耦合:一个接口要包含完整的业务功能,而不同接口之间的业务关联要尽可能的小。
    4. 分析角度明确:设计接口分析的角度要统一明确。否则会造成接口结构的混乱。
    5. 入参格式统一:所有接口的参数格式要求及风格要统一,不要一个接口参数是逗号分隔,另一个就是数组;不要一个接口日期参数是x年x月x日风格,另一个就是x-x-x。
    6. 状态及消息:提供必要的接口调用状态信息。调用是否成功?如果失败,那么失败的原因是什么。这些必要的信息必须要告诉给客户端。
    7. 控制数据量:一个接口返回不应该包含过多的数据量,过多的数据量不仅处理复杂,对数据传输的压力也非常大,会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。
    展开全文
  • 接口文档实例

    2020-07-30 23:33:32
    接口文档的描述. 甲方节点和乙方节点的同意.
  • 接口文档

    万次阅读 2018-05-08 16:50:24
    1 接入方式说明1.1 调用入口测试环境:http://18test-app.stg3.1768.com/ItemSubaccount1.2 消息结构1.3 接口请求结构如下:{ "head":{ //报文头 "apiVersion": "", //报文版本...
  • API接口入门:读懂API接口文档

    千次阅读 多人点赞 2019-10-23 14:04:46
    本文目录: API接口是什么? 为什么我们需要API接口? API接口的核心 一、API接口是什么? 我们来以一个常见的数学公式理解API,比如y=x+2,当x=2的时候,y=4,对么?...API接口入门(一):读懂API接口文档 类...
  • 接口&接口文档

    万次阅读 2018-09-02 23:16:41
    一、接口简介 API(Application Programming Interface)即应用程序接口,可以任务是一个软件组件或一个Web服务与外界进行交互的接口,在这里接口可以和API划等号。 接口可以简单的理解为一个黑盒子,从一边输入...
  • 接口模板 接口文档

    千次下载 热门讨论 2020-07-30 23:30:23
    接口模板 接口文档
  • api接口文档模板

    热门讨论 2020-07-27 23:31:02
    api接口文档模板
  • 接口文档 切图标注 对接的部门,包括但不仅局限于 前端和后端 移动端和后端 设计和前端 设计和移动端 产品经理和开发 老板和产品经理 那么,在这些沟通中产生的文档,该怎么保存、归档,该怎么阅读、使用,就...
  • 常用接口文档模板(markdown版)

    万次阅读 2018-07-20 20:24:35
    1. 查询指定项目属性接口 1. 查询指定项目属性 接口功能 获取制定项目的分类信息 URL http://www.api.com/index.php 支持格式 JSON HTTP请求方式 GET 请求参数 参数 必选...
  • Spring项目集成apidoc生成api接口文档

    万次阅读 2018-01-29 14:38:41
     JavaWeb/spring项目写成的api接口,需要自动生成api文档,甚至需要在线测试接口。考虑实现的方案有swagger,apidoc,spring rest docs。在之后的项目都有一一尝试,最终还是觉得apidoc的方式比较合适,虽然有一些...
  • 接口文档要如何写

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

    万次阅读 2016-07-03 21:02:14
    接口测试的依据,往往不是需求文档,而是接口文档。 那么,接口文档的准确性便至关重要,本文推荐两种形式的接口文档,供大家参考。 接口文档不管以什么形式存在,需要包含的内容有: 接口名称接口类型输入...
  • 完整接口文档见http://download.csdn.net/download/qq_36467463/10214090
  • 接口文档示例

    千次阅读 2019-08-15 17:15:40
    接口文档示例用户登录注册登录注册树形菜单增删查改查增删改 用户登录注册 登录 http请求方式: POST(请使用https协议) https://localhost:8080/hu/vue/userAction_login.action 参数 是否必须 说明 uname...
  • 接口文档相关问题

    千次阅读 2019-11-01 17:30:15
    接口文档相关内容
  • 【SpringBoot】廿二、SpringBoot中整合knife4j接口文档

    千次阅读 多人点赞 2020-07-02 16:13:51
    在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个...
  • laravel接口 接口文档

    千次阅读 多人点赞 2018-11-11 19:07:29
    接口 先在控制器里写一个接口的方法 之所以写了两个方法 因为写接口单独创建一个控制器比较好 避免与页面展示冲突 // 展示页面 配合城市接口执行 public function cityshow(){ $data = DB::table('jy_city')-&...
1 2 3 4 5 ... 20
收藏数 789,033
精华内容 315,613
关键字:

接口文档