API文档
刚开始工作,按照要求需要编写API文档,先查点资料学习,正好记录一下,如有错误请指正。
API(Application Programming Interface 应用程序编程接口)通常是一些预定义的函数,其主要目的是为应用程序和开发人员提供基于软件访问一段例程的便利方式。API的使用者无需知道接口内部如何实现或源码细节,只需要知道该段例程的功能,输入相应参数即可得到返回结果。
API文档实际上是一个技术内容交付文件,主要是一些API的说明和具体使用示例。简单来看就是一份说明书,包含了使用API的所需信息,详细介绍参数、函数、类、返回类型等。编写API文档时需要包含以下几个部分:
- 接口描述
简介接口逻辑和功能。 - 接口地址
接口的正式地址和测试地址。 - 请求方法
通常是读接口和写接口两种方式,以此来实现对数据的查看和更改。 - 请求参数
需要请求的字段名称和规则,例如有哪些字段、类型是什么、是否为必填字段等。 - 响应内容
接口返回的字段名和和规则。 - 错误代码
对接口的错误用法代码进行归类,以便能快速定位错误。 - 示例
实际调用时的响应结果。
Note:大部分API文档不会把所有字段列出,通常只列出重要字段。