文档规范 ======== 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 接口请求和返回示例