这是一个创建于 2898 天前的主题，其中的信息可能已经有所发展或是发生改变。
目前公司后端接口统一使用的是 office 。 也就是后端开发完成后，自己用 postman 测试，测试完毕后将参数和结果都写到 word 上。然后将 word 分类管理好后提供给前端，让前端根据 word 查看。
但是使用这种方法遇到一些问题。
- 本身 word 对编程语言的支持不够丰富，各种格式的数据拷贝过来就错乱了。想要在 word 里进行 json 的编辑也是非常不方便
- 是前端人员无法一目了然对整个文档有所了解。我虽然知道有目录这种东西，但是 office 也是有学习成本滴！
- 公司的程序员都比较抵触 office 。
不知道大家的公司怎么处理这个问题的？ 我现在的思路是换成 markdown 标记语言，然后通过 markdown 来解决这个问题不知道如何？
自己搭 1 个类似博客系统一样的东西，然后展示 markdown 。不知道这方面有什么成熟的解决方案没有？ 集思广益，谢谢大家！
 |
1
konakona 2016-12-19 23:53:32 +08:00
早期用 WIKI ，学习成本较高。
现在有了 Markdown ，还犹豫什么？ |
|
2
konakona 2016-12-19 23:54:43 +08:00
得举个 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 | 是 | 课程标题 | ---- |
 |
4
mopvhs 2016-12-20 00:35:48 +08:00
|
 |
5
mrytsr 2016-12-20 05:48:43 +08:00 via Android
curl
|
 |
6
donieleigh 2016-12-20 10:19:47 +08:00 via iPad
团队抵制 office 说明水平比较高。我虽然觉得 markdown 比 office 好太多，但还是不够优雅，持续关注。
|
 |
7
baiyi 2016-12-20 10:51:34 +08:00
http://www.showdoc.cc/ 这个用着还不错,markdown 语法的,自带个模板
|
 |
8
xuwenhao 2016-12-20 11:15:44 +08:00 via iPhone
swagger 啊
|
 |
9
chairuosen 2016-12-20 11:52:10 +08:00
当然 markdown 啊，配个 blog 系统可以 web 端查看，还可以全局查找接口，查看背锅人，版本控制，语法高亮，不要太爽。
|
 |
10
mzeht 2017-01-19 22:43:01 +08:00
|
Select Language