2.1.3. 文档规范¶
README 规范:
# 项目名称
<!-- 写一段简短的话描述项目 -->
## 功能特性
<!-- 描述该项目的核心功能点 -->
## 软件架构 (可选)
<!-- 可以描述下项目的架构 -->
## 快速开始
### 依赖检查
<!-- 描述该项目的依赖，比如依赖的包、工具或者其他任何依赖项 -->
### 构建
<!-- 描述如何构建该项目 -->
### 运行
<!-- 描述如何运行该项目 -->
## 使用指南
<!-- 描述如何使用该项目 -->
## 如何贡献
<!-- 告诉其他开发者如果给该项目贡献源码 -->
项目文档规范:
包括一切需要文档化的内容，它们通常集中放在 /docs 目录下
好的文档规范有 2 个优点：易读和可以快速定位文档。
不同项目有不同的文档需求，在制定文档规范时，你可以考虑包含两类文档:
1. 开发文档
用来说明该项目的开发流程，比如如何搭建开发环境、构建二进制文件、测试、部署等
2. 用户文档
软件的使用文档，对象一般是软件的使用者，内容可根据需要添加
比如，可以包括 API 文档、SDK 文档、安装文档、功能介绍文档、最佳实践、操作指南、常见问题等
为了方便全球开发者和用户使用，开发文档和用户文档，可以预先规划好英文和中文 2 个版本
实战项目的文档目录结构:
docs
├── devel # 开发文档，可以提前规划好，英文版文档和中文版文档
│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构
│ └── zh-CN # 中文版文档，可以根据需要组织文件结构
│ └── development.md # 开发手册，可以说明如何编译、构建、运行项目
├── guide # 用户文档
│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构
│ └── zh-CN # 中文版文档，可以根据需要组织文件结构
│ ├── api/ # API 文档
│ ├── best-practice # 最佳实践，存放一些比较重要的实践文章
│ │ └── authorization.md
│ ├── faq # 常见问题
│ │ ├── iam-apiserver
│ │ └── installation
│ ├── installation # 安装文档
│ │ └── installation.md
│ ├── introduction/ # 产品介绍文档
│ ├── operation-guide # 操作指南，可以根据 RESTful 资源再划分为更细的子目录
│ │ ├── policy.md # 用来存放系统核心 / 全部功能的操作手册
API 接口文档规范¶
一个规范的 API 接口文档，通常需要包含:
1. API 接口介绍文档
2. API 接口变更历史文档
3. 通用说明
4. 数据结构说明
5. 错误码描述
6. API 接口使用文档
API 接口使用文档中需要包含:
a. 接口描述
b. 请求方法
c. 请求参数
d. 输出参数
e. 请求示例
接口文档拆分为以下几个 Markdown 文件:
1. README.md
API 接口介绍文档，会分类介绍支持的 API 接口，并会存放相关 API 接口文档的链接，方便开发者查看
2. CHANGELOG.md
API 接口文档变更历史，方便进行历史回溯，也可以使调用者决定是否进行功能更新和版本更新
3. generic.md
用来说明通用的请求参数、返回参数、认证方法和请求方法等
4. struct.md
用来列出接口文档中使用的数据结构
这些数据结构可能被多个 API 接口使用，会在其他文件中被引用
5. user.md 、 secret.md 、 policy.md
详细的API 接口文档，相同 REST 资源的接口会存放在一个文件中，以 REST 资源名命名文档名
6. error_code.md ：错误码描述，通过程序自动生成
详细接口实例-user.md 为例:
1. 接口描述
描述接口实现了什么功能
2. 请求方法
接口的请求方法，格式为 HTTP 方法请求路径，例如: POST /v1/users
在通用说明中的请求方法部分，会说明接口的请求协议和请求地址
3. 输入参数
接口的输入字段，它又分为 Header 参数、Query 参数、Body 参数、Path 参数
每个字段通过: 参数名称、必选、类型 和 描述 4 个属性来描述
如果参数有限制或者默认值，可以在描述部分注明
4. 输出参数
接口的返回字段，每个字段通过 参数名称、类型 和 描述 3 个属性来描述
5. 请求示例
一个真实的 API 接口请求和返回示例