[大概算项目管理] 关于后端接口的文档问题？小创业公司如何应对接口问题呢？

This topic created in 3432 days ago, the information mentioned may be changed or developed.

目前公司后端接口统一使用的是 office 。也就是后端开发完成后，自己用 postman 测试，测试完毕后将参数和结果都写到 word 上。然后将 word 分类管理好后提供给前端，让前端根据 word 查看。

但是使用这种方法遇到一些问题。

本身 word 对编程语言的支持不够丰富，各种格式的数据拷贝过来就错乱了。想要在 word 里进行 json 的编辑也是非常不方便
是前端人员无法一目了然对整个文档有所了解。我虽然知道有目录这种东西，但是 office 也是有学习成本滴！
公司的程序员都比较抵触 office 。

不知道大家的公司怎么处理这个问题的？我现在的思路是换成 markdown 标记语言，然后通过 markdown 来解决这个问题不知道如何？

自己搭 1 个类似博客系统一样的东西，然后展示 markdown 。不知道这方面有什么成熟的解决方案没有？集思广益，谢谢大家！

10 replies • 2017-01-19 22:43:01 +08:00

konakona

Dec 19, 2016

早期用 WIKI ，学习成本较高。
现在有了 Markdown ，还犹豫什么？

konakona

Dec 19, 2016

得举个 easy - API 例：

###课程列表（周历模式）###

请求地址：[/syllabus/index]( http://api.***.com/syllabus/index)

请求方式： GET

请求参数：

| 参数名 | 参数类型 | 是否必须 | 说明 |
| ----- | ---- | ---- | ------------------------ |
| month | int | 是 | 月份，不足 2 位数请补 0 |
| year | int | 否 | 如果不是今年的查询，请带上此参数，比如： 2014 |

返回参数：`data`

`data`中由 7 个日期数组组成，日期数组中有可能为空，这代表那天没有任何安排。

| 参数名 | 参数类型 | 是否必须 | 说明 |
| ------------ | ------ | ---- | -------------------------------------- |
| id | int | 是 | PKID |
| start_time | string | 是 | 开始日期和时间，没有秒。格式： YYYY-mm-dd HH:ii |
| end_time | string | 是 | 结束日期和时间，没有秒。格式： YYYY-mm-dd HH:ii |
| color | string | 否 | 颜色的 HEX 值，有可能为空，此时需要 APP 做默认颜色处理 |
| teacher_name | string | 是 | 导师姓名 |
| status | int | 是 | 请假申请状态值。默认为 0 代表没有请假，如果为 1 代表有请假。此时应改变背景色。 |
| status | int | 是 | 课程状态值 |
| class_name | string | 是 | 课程标题 |

----