十年架构师告诉你怎样写好接口文档

前言：

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

文章目的：

1.个人对于写接口文档的一些资料整理。

2.学习如何写一份别人乐意去看的文档。

3.希望可以通过本文帮助处理那些面临自己写接口文档的情况下无从下手的尴尬的局面。

接口文档书写

1. 前置描述

●产品文档，简单说明背景，接口用来干嘛的

●技术文档，说一说各方的具体实现，复杂的可以说下具体的设计思路，n个方案对比，贴上sql，ddl，dml设计，具体代码等具体能看的东西

2. 方法概览

●方法路径，命名统一

●方法名称，命名统一

●方法类型 get/post…

3. 参数定义

●参数命名统一，下划线，驼峰…

●类型定义明确，整形，长整型，浮点，对象，指针

●是否需要枚举 required Enuma a

●是否必填 optional int a //非必填

●必要备注，说明这个字段是干啥的 required int a //不能叫a

●是否需要默认值 required int a =0

●如果是比较难懂的字段，贴上相关说明链接 required int a //字段说明http:heheda.com

●如果是部分有特殊意义的string或者数组，举例子说明含义，比如 yyyy-mm-dd类型的string

●需要提供idl文件的或者webservice，注意格式化

●http请求可以给到示范的请求返回

●如果是接口变更，用特殊标记表示，比如字体加红

简单版本

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

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

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

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

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

最佳方式：word -> pdf

简单版本的目录格式

●接口说明

●请求示例

●请求参数说明

●响应示例

●响应参数说明

案例模板1：

接口说明：

接口功能：

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

接口请求地址：

https: xxx/xxx/xxxx

请求头 :