doc_rules.md
1.4 KB
开发文档规范
1. 概要
- 公司中，开发文档全部使用md文件，上传到项目对应的Gitlab中。
- 文档写作辅助工具包括:
- Typora / MarkdownPro : MD文档撰写工具
- XMind : 思维导图工具
- Visio : 流程图工具
- 任何一个项目，以下文档不可缺，且随着开发的不断进行，也需要不断的更新
- API接口文档 及 API接口特别说明文档
- 数据库文档
- 与其它系统交互的系统交互文档
- 功能复杂的流程图
- 代码文件的phpDoc文档
2.API文档
2.1 API文档做成约定
API文档默认放在各项目 S2_Project | P1_API 目录下。此目录定义了暴露给外部应用的每个接口的参数和返回值。
在写API文档时，规约包含以下几个方面:
各个API必须以独一的形式进行编号。
每个API文档必须定义版本，在应用层上的版本和API文档的版本必须一致。
API文档必须给出地址的PATH路径值。
API文档必须给出调用的HTTP方法: GET | POST | DELETE | PUT
API文档必须给出应答的格式，默认为JSON
API的请求参数必须要详细说明，说明包括:
类型 / 是否必须 / 备注
如果参数不同，带来的返回值有很大的差异，在需要说明的情况下，也必须落实成文档。
- API的返回值的参数也必须要详细说明。说明包括:
返回示例，返回各数据的类型， 返回各数据的详细说明。
如果有些返回值是可选的，也需要给出说明。
每个API文档下方必须要存在更新备注信息。当每一次更新API，除了修改文档，也在下方写明备注原因。
因升级，过时的API必须标注为depreciated.
如果此API依赖于其它的系统交互，需要给出其它系统流程的文档跳转地址。
对于复杂的API（如用户验证、支付、订单流转等），需要额外定义文档，