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

[mikulch]

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

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

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

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

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

[konakona]

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

[konakona]

得举个 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 | 是 | 课程标题 |

----

[mikulch]

@konakona
感谢！十分有用！

[mopvhs]

Swagger – The World's Most Popular Framework for APIs.

例子： http://petstore.swagger.io/

这个非常棒！

[mrytsr]

curl

[donieleigh]

团队抵制 office 说明水平比较高。我虽然觉得 markdown 比 office 好太多，但还是不够优雅，持续关注。

[baiyi]

http://www.showdoc.cc/ 这个用着还不错,markdown 语法的,自带个模板

[xuwenhao]

swagger 啊

[chairuosen]

当然 markdown 啊，配个 blog 系统可以 web 端查看，还可以全局查找接口，查看背锅人，版本控制，语法高亮，不要太爽。

[mzeht]

http://rap.taobao.org/org/index.do