如何写一份优秀的接口文档(上)

简介: 如何写一份优秀的接口文档(上)

前言:



最近看了很多写的非常好的接口文档,在理解业务方面给了非常多的帮助,解决很多时候对于一些协商数据的问题困扰,同时,后续个人的工作当中,也需要对外开放接口给第三方进行调用,这时候一个好的规范文档可以解决很多问题。


文章目的:



  1. 个人对于写接口文档的一些资料整理。
  2. 学习如何写一份别人乐意去看的文档。
  3. 希望可以通过本文帮助处理那些面临自己写接口文档的情况下无从下手的尴尬的局面。


目录:



主要分为以下两个版本,两个版本各有各自的特点,需要应对不同的应用场景

  1. 简单版本
  2. 复杂版本


简单版本



核心:如果你的案例可以直接依靠复制拿来使用,那这个文档就是好文档

既然要简单,那就抓住核心:怎么简单怎么来,怎么省时间怎么来

如果不知道怎么写,就把案例写的越详细越好

开发时间是非常宝贵的,而接口对接通常都是一些工期紧张的情况下去快速编写,而且面对一些碎片化的时间工作者,一份简单直观的文档可能更受欢迎。

另外,接口文档最终形式最好是pdf,以前遇到过接口文档写到word里面的,在不同的版本下可能会出现样式等各种问题

最佳方式:word -> pdf


简单版本的目录格式


  • 接口说明
  • 请求示例
  • 请求参数说明
  • 响应示例
  • 响应参数说明


案例模板1:



接口说明:

接口功能:

本接口用于获取用户的token信息。

接口请求地址:


https: xxx/xxx/xxxx
复制代码


请求头 :


请求头 请求内容 说明
Authorization Basic secretKey 访问token
Content-Type application/json 请求方式


请求方式:  POST

参数类型JSON

请求示例:

绝大多数为json,格式自定


[
    {"id":"20201219",
     "name":"21.59",
     "age":"ftp_1002"
     ...
    },
    {"id":"20201219",
     "name":"21.59",
     "age":"ftp_1002"
     ...
    },
]
复制代码


请求参数说明


字段名 字段说明 字段类型 是否必填
字段1 说明字段1的作用 varchar(50)
字段2 说明字段2的作用 int
字段3 说明字段3的作用 decimal


响应示例

成功响应编码:


{
    "code: "200",
    "message": "请求成功",
    "data": 返回数据,格式自定
}
复制代码


失败响应编码:


{
    "code: "200",
    "message": "请求成功",
    "data": 返回数据,格式自定
}
复制代码


响应参数说明


接口返回码 接口返回描述
200 成功
400 请求参数异常
401 授权失败
500 系统异常


案例模板2:



下面这种模板是单个接口的适合很实用,同时针对一些比较简单的接口这样处理还算比较直观

核心是一个表包含所有信息,这对于一些接口量非常非常大的时候或者接口参数相似的时候比较有效果,这样可以使得内容比较紧凑,不会看了下一页忘记上一页的烦恼,当然缺点也很明显,会存在文字堆积的情况。

markdown的表格在存放Json的数据时候不是很直观,建议使用word


接口名 UserUpdateService
接口请求地址 www.baidu.com
功能说明 UserUpdateService接口是应用系统的账号修改方法
请求参数 参数名 中文说明
RequestId 平台每次调用生成的随机ID,应用系统每次响应返回此ID,String类型
uid 三方应用系统账号创建时,返回给应用系统的账号主键uid。必传字段
loginName/ fullName 需要修改的账号字段属性
响应参数 参数名 中文说明
RequestId 平台每次调用接口发送的请求ID,字段为String类型
resultCode 接口调用处理的结果码,0为正常处理,其它值由应用系统定义。字段为String类型,必传字段
message 接口调用处理的信息。字段为String类型
请求示例: { “token”,””, “treeCode”,” EXECUTIVE”, “code”,””} markdown展示不是很好看,建议word
返回值 { "xxxx": "xxxxxx", "resultCode": "0", "message": "success" } markdown展示不是很好看,建议word


案例模板3:



下面这种可能不是很直观,但是参考很多文档发现好像类似的还不少,也可以参考一下。


请求地址:http://www.baidu.com

l 属性列表


属性名 中文命名 值类型 值必须 描述
token 令牌 String
treeCode 机构树编码 String 如果为空表示根机构,默认填写” ROOT”
code 机构代码 String
start_date 开始日期 Date 合同或项目的开始日期
name 机构名称 String
end_date 结束日期 Date 合同或项目的结束日期
user_num 驻点人员数量 Int
supplier_name 供应商名称 String
type 机构类型 String 项目机构ProjectOrg,行政机构AdministrativeOrg
orgUpCode 上层机构代码 String
parentId 父机构code String
isDisabled 是否禁用 Boolean false

l 响应属性列表

属性名 中文命名 值类型 值必须 描述
code 返回码 String
message 返回信息 String 如果为空表示根机构,默认填写” ROOT”
data 返回内容 String


l JSON数据示例**


[http://xxxxxxxx/xxx/xxx]
请求参数:
"
    {
        “token”,””,               //必填
        “treeCode”,” EXECUTIVE”,  //必填
        “code”,””,                //必填
        “entity”,” {
        "code":"2222",            //必填
        " start_date":"",
        "name":"字段名称",         //必填
        "end_date ":"",   
        "user_num":"",
        "supplier_name":"",
        “type”,””,   //指定类型  
        "orgUpCode":"11111",      //必填
        "parentId":"1111111",    //必填
        “isDisabled”:” false”    //是否禁用
    }
"
响应:login
JSON - 数据示例
{
 "success": true,
 "data": {
     "treeId": "ROOT",
     "parentId": 112034,
     "name": "3333",
 },
 "errorCode": null,
 "errorName": null,
 "errorMessage": null,
 "errorException": {
  "name": null,
  "message": null,
  "trace": null
 }
}
复制代码


至此,一个简单的接口文档差不多就是这些内容,下面将会介绍一下复杂的做法(内容较多)


复杂版本



由于不同的公司有不同的文档格式要求,这里只给出我看过的几个文档罗列下来的一些文档内容,不一定通用,也不一定是很完美的,但是希望内容可以具备一定的参考价值。


复杂版本的内容有点多。请耐心观看或者收藏再看(=v=)


复杂版本的目录格式


+ 封面
  + 接口文档名称
  + 接口版本号
  + 版权说明
+ 文档信息
  + 标题 | 创建时间 | 打印时间 | 文件名 | 存放目录 | 所有者 | 作用
  + 小题:版权声明
+ 版本历史(重点1)
  + \| 版本号 \| 日期 \| 修改者 \| 描述 \|
  + \| v1.0.0  \| xxx \| xxx \| xxx |
+ 目录
  + 结构清晰
  + 有条理
  + 能快速定位需要的信息(后文会介绍)
+ 文档具体内容部分
  + 编写目的
  + 对接准备事项
    + 测试联调
    + 上线
  + 使用协议 + 规范
  + 报文规范
    + 请求报文规范
    + 响应报文规范
  + 接口描述
    + 报文规范
      + 请求报文
      + 响应报文
      + 公共报文头
      + 接口码说明
      + 业务接口
      + 查询接口
    + 加解密规范
      + 原则
      + 令牌信息
      + 加密规范
      + 解密规范
  + 业务接口
    + 具体接口1:
      + 说明
      + 规范码(查表)
      + 使用方式
      + 请求字段
      + 响应字段
      + 案例
    + 具体接口2....
    ........
  + 附录
    + 参考资料1
    + 参考资料2
  + 其他.....
复制代码


目录
打赏
0
0
0
0
4
分享
相关文章
|
8月前
如何写出一份优秀的技术简历?
如何写出一份优秀的技术简历?
102 0
如何读懂接口文档,简单易懂
一份设计得当的接口文档会用自己的方式回答上述问题,它通常会包含以下要素: 接口简介(回答接口是干嘛用的?) 定义请求协议(回答接口怎么用?) 请求地址源 请求方式 请求参数 返回参数示例(回答接口后的返回结果是什么?) 状态码
如何读懂接口文档,简单易懂
如何写一份优秀的接口文档
下面这种模板是单个接口的适合很实用,同时针对一些比较简单的接口这样处理还算比较直观
361 0
怎么写一份好的接口文档?
编写一份优秀的接口文档会让软件开发中变得更加轻松,更有效率。这可是关键任务,写得好不仅可以帮助开发人员更好地理解和使用 API 接口,还可以提高整个团队的协作效率。
Java开发都需要参考的一份命名规范
好的命名能体现出代码的特征,含义或者是用途,让阅读者可以根据名称的含义快速厘清程序的脉络。不同语言中采用的命名形式大相径庭,Java中常用到的命名形式共有三种,既首字母大写的UpperCamelCase,首字母小写的lowerCamelCase以及全部大写的并用下划线分割单词的UPPERCAMELUNSER_SCORE。通常约定,类一般采用大驼峰命名,方法和局部变量使用小驼峰命名,而大写下划线命名通常是常量和枚举中使用。
454 0
Java开发都需要参考的一份命名规范