最近工作上碰见了需要些api相关的需求，但是作为初出茅庐的菜鸡，对于这种工程性的东西不论是写的格式还是内容都不是那么规范，于是总结学习了一下各个大佬们的书写方法以及网上的很多模板，自己总结了这么一篇文章

文档名称、标题和概述

写我们的api文档时，文档的名称和标题尽可能以 XXX项目API文档作为开始标题，示例如下

Sample项目的API文档

并在文档的标题后跟进我们的概述，概述主要声明以下内容：

  • 适用范围
  • api功能
  • 是否维护
  • 版本以及修改日期

写一个简单的例子的话就是：

1.概述

Sample 项目 是用于完成前端与后端

本文档只适用于前端和后端开发使用，API内容可能会发生改变，届时后端将会与前端就具体改动进行探讨，并将最终改动方案提交到本文档。

本文档中有关数据模型的相关陈述已在后端数据文档中详细论述，请参阅后端数据文档。

本文版本，修改日期，修改内容列表如下：

版本 日期 详情
v0.1 xxxx年xx月xx日 本版本为该项目的最初版本

项目的认证信息

这一部分是可选的内容，如果你的项目不存在认证，那么这一部分就可以完美跳过了，如果有的话，那么还是建议将这一部分完善好

这里应该详细的去描述应该如何去获取相关的key/token等信息，以及计算对应sign的方法，当然还不要忘了多写一些示例

2.认证鉴权

（1） 获取认证的方式：

​ 打开XXXX，然后点击XXXX，获取对应的Token和Key

（2）计算sign的逻辑

​ 基于 XXXX算法，将XXXX作为盐值，对 Token 和 Key 进行哈希计算，进而 生成认证签名 sign

（3）计算示例

1
2
import *
......
1
2
fn main(){
.............

接口的相关信息

这一部分是最关键的一部分，所以要尽可能的详细详细再详细，对于这一部分的内容整体的分布还需要根据项目来决定，这里只给出整体框架和部分细节来看

首先是path信息，如果项目不只是一个api的情况下，我们需要给出path的信息，并简要描述该api的作用，可以理解为这是项目接口的一个目录

接口列表

  • \XXX\XX xxxxxxx
  • \XXX\XX1 xxxxxx

在这之后我们就可以根据接口一个个的来写了，首先是http请求类型和调用的基本信息，在这里需要你说明白参数，参数位置，类型等，当然特定情况下还需要写明默认值，是否必须，以及样例等。

xxx基本信息

请求地址:xxxxx

请求方法: xxx

Content-Type: xxx

Accept: xxxxxx

xxx参数（这里可以是body，query等等，取决于你传入的位置）

参数 是否必须 类型 说明信息
id 是 int xxxx
name 否 string xxxx
age 否 Map<Age,Session> xxxx

到这里的时候，我们发现我们写的参数中出现了我们自定义的结构，那么我们也要把他们的结构说明

Age结构

参数 是否必须 类型 说明信息
true-age 是 int xxxx
game-age 是 int xxxx

那么到这里后结束了吗？既然有请求的信息，那么返回的部分也也要写明白，返回的参数，类型以及响应码，响应码是很重要的部分！！状态码的规范尽可能要保证 0是标准，小于1的属于错误类型，大于1的属于某种状态

响应说明

数 是否必须 类型 说明信息
code 是 响应码(int) xxxx
name 否 string xxxx

状态码

代码 信息
1 XXX
0 XXX
-1 XXX

如果以上内容全部完成后，那么恭喜你，已经完成报告最多的一个部分了

附录

附录这一部分是非必须的内容之一，但是对于文档多多少少会带上附件，所以尽可能的把这些东西标上也更规范一点，当然不只是文件，还可以是一些其他的信息或者表格等等，安装标号记录好

附录：

  1. api源码文件.zip
  2. XXXXX

API框架基本配置信息：

……

主要贡献人员：

……

问答

这一部分则是可以不断添加的一个部分，对于上文中无法描述的零散问题，以及在项目运行中经常涉及的问题，再或者是当前Api的bug，这一部分都可以通过问答来进行描述，问答的内容不一定真的存在“问答”，但存在“问答”的问题一定要在问答之中

F&Q

问题1

Q：XXXXXXX

A：XXXXXXX

问题2

Q:XXXXXXXX

A：XXXXXXX

……

更新日志

最后就是更新日志了，更新日志的规范要注意版本号，时间，以及更新的内容了，虽然只有三部分，但这三部分也有很多的细节。

首先是版本号，版本号应该如何去取，又该取避免怎样的错误，这里不多赘述，有兴趣的可以去看一下这几篇文章：

【知识整理】软件版本号及规范 - 知乎

版本号命名规范 | Jay 的博客

时间的话只需要按照同一种规定去写就好了，最后是内容这一部分，内容不需要写的面面俱到，而是要把握更新的重要内容，将本次更新的重点内容描述出来即可。当然如果有需要，可以在每个大版本后面后面添加迁移方案

更新日志

v0.1.0

2025-10-13

  • 添加了XXXXXXXXXXX
  • 修复了XXXXXXXXXXX
  • 改动XXXXXX

更多规范

除了以上文体的部分，还有以下格式的内容也要注意，这里推荐这篇文章

ruanyf/document-style-guide: 中文技术文档的写作规范