API接口文档怎么写？

API接口文档模板

当涉及到编写API接口文档时，一个清晰、详尽的模板是至关重要的。API接口文档不仅仅是对系统功能和数据端点的描述，更是开发者们理解和利用你的API的关键入口。在这篇博客中，我们将提供一个全面的API接口文档模板，旨在帮助开发团队有效地记录、理解和使用API。
无论是内部使用还是对外开放，一个优秀的API文档都应该具备几个关键特征：清晰的结构、易于导航的目录、详细的端点描述、示例请求和响应、以及任何相关的注意事项或限制。通过本文提供的模板，你可以轻松地创建符合这些标准的API文档，从而提高开发效率、减少沟通成本，并增强API的可用性和可维护性。
无论你是新手还是有经验的开发者，本文都将为你提供一个简单而全面的起点，帮助你创建出令人满意的API接口文档。

本文档更新时间：2022-12-07

本文档更新说明：提供了接口文档模板，后续如果有接口文档编写相关工作，可以参考该模板。

接口名称： XX帐号基础信息批量获取接口 【接口名称，见名知意】

接口版本： v1.0.0 【接口版本号】

接口地址： http://XXX/api/account/get_list_xxx 【接口地址需要拼接URL+端口号，默认端口号80】

请求方式： GET/POST 【接口的请求方式，GET或POST】

请求头（Header）参数：

字段名	类型	描述
app-key	string	合作商身份标识
api-version	string	请求接口版本号
timestamp	string	接口请求访问时间，2022-12-07 19:08:30

【注：接口若有请求头（Header）参数，需要填写参数的字段名称、字段类型、该字段的必要文字描述。也可以新添加一列，描述字段的默认值。】

请求体（Body）参数：

字段名	类型	描述
page	int	页码，默认值为1
perpage	int	每页返回账号的数量，默认100
sort	string	排序字段，默认为1正序，2倒序。支持最多5个字段排序，多个排序字段用","隔开，例如：price_post-1, klr_index-2
account_uid	string	账号uid
media_id	string	账号唯一标识id
follower_max	int	粉丝数上限
follower_min	int	粉丝数下限

【注：请求体（Body）参数中，需要填写参数的字段名称、字段类型、该字段的必要文字描述。】

返回参数：

字段名	类型	描述
account_uid	string	账号UID
account_name	string	账号昵称
account_class	string	帐号分类
account_followers	string	帐号粉丝量
media_id	int	资源中心账号唯一标识ID
avatar	string	头像的URL链接
account_desc	string	账号描述
verified_reason	string	大V认证描述
klr_index	int	指数
article_count	int	账号博文数量

【注：需要介绍接口返回参数中的核心字段，如：字段名、字段类型、字段描述。】

返回示例：

{
    "code": 10000,
    "msg": "请求成功",
    "data": {
        "pagination": {
            "has_next": false,
            "current_page": 1,
            "total_page": 1,
            "total_count": 1,
            "perpage": 100
        },
        "data": [
            {
                "account_uid": "1344360230",
                "account_name": "Kevin凯文老师",
                "account_class": [
                    "美妆时尚"
                ],
                "account_followers": 54863320,
                "avatar": "http://tvax4.sinaimg.cn/crop.90.414.792.792.180/50214f26ly8g1oaw8s0rrj20u01900x1.jpg",
                "account_desc": "会摄影会做饭、喜欢血拼种草的“彩妆小弟”，当然你如果想跟我学英语也是可以的…",
                "verified_reason": "著名造型师 故事红人 签约自媒体",
                "article_count": 14530,
                "klr_index": "89.4",
                "media_id": 740131,
            }
        ]
    }
}

【注：在返回示例的位置粘贴返回的json代码，方便看清接口返回的层次信息。】

异常返回示例：

{
    "code": 10002,
    "msg": "签名错误",
    "data": []
}

【注：需要介绍非成功状态下的接口返回示例，方便接口调用方做异常处理。】

常见的接口状态返回码：

字段	描述
10000	请求成功
10001	客户端身份异常
10002	签名错误
10003	访问次数频繁
10004	接口参数异常
10005	接口限制访问