主页

索引

模块索引

搜索页面

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 接口请求和返回示例

主页

索引

模块索引

搜索页面