写好接口文档的方法

  1HTTP携带信息的方式
 
  url
 
  headers
 
  body:包括请求体,响应体
 
  2分离通用信息
 
  一般来说,headers里的信息都是通用的,可以提前说明,作为默认参数
 
  3路径中的参数表达式
 
  URL中参数表达式使用mustache的形式,参数包裹在双大括号之中{{paramName}}
 
  例如:
 
  /api/user/{{userId}}
 
  /api/user/{{userType}}?age={{age}}&gender={{gender}}
 
  4数据模型定义
 
  数据模型定义包括:
 
  路径与查询字符串参数模型
 
  请求体参数模型
 
  响应体参数模型
 
  数据模型的最小数据集:
 
  名称
 
  是否必须
 
  说明
 
  “最小数据集”(MDS)是指通过收集最少的数据,较好地掌握一个研究对象所具有的特点或一件事情、一份工作所处的状态,其核心是针对被观察的对象建立起一套精简实用的数据指标。最小数据集的概念起源于美国的医疗领域。最小数据集的产生源于信息交换的需要,就好比上下级质量技术监督部门之间、企业与质量技术监督部门之间、质量技术监督部门与社会公众之间都存在着信息交换的需求。
 
  一些文档里可能会加入字段的类型,但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化,大部分数据类型都是字符串。一些特殊的类型,例如枚举类型的字符串,可以在说明里描述。
 
  另外:数据模型非常建议使用表格来表现。








本文转载自中文网
 

推荐阅读