V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
mikulch
V2EX  ›  问与答

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

  •  
  •   mikulch · 2016-12-19 23:07:00 +08:00 · 2077 次点击
    这是一个创建于 2900 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

    10 条回复    2017-01-19 22:43:01 +08:00
    konakona
        1
    konakona  
       2016-12-19 23:53:32 +08:00
    早期用 WIKI ,学习成本较高。
    现在有了 Markdown ,还犹豫什么?
    konakona
        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 | 是 | 课程标题 |

    ----
    mikulch
        3
    mikulch  
    OP
       2016-12-20 00:35:37 +08:00
    @konakona
    感谢!十分有用!
    mopvhs
        4
    mopvhs  
       2016-12-20 00:35:48 +08:00
    Swagger – The World's Most Popular Framework for APIs.

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

    这个非常棒!
    mrytsr
        5
    mrytsr  
       2016-12-20 05:48:43 +08:00 via Android
    curl
    donieleigh
        6
    donieleigh  
       2016-12-20 10:19:47 +08:00 via iPad
    团队抵制 office 说明水平比较高。我虽然觉得 markdown 比 office 好太多,但还是不够优雅,持续关注。
    baiyi
        7
    baiyi  
       2016-12-20 10:51:34 +08:00
    http://www.showdoc.cc/ 这个用着还不错,markdown 语法的,自带个模板
    xuwenhao
        8
    xuwenhao  
       2016-12-20 11:15:44 +08:00 via iPhone
    swagger 啊
    chairuosen
        9
    chairuosen  
       2016-12-20 11:52:10 +08:00
    当然 markdown 啊,配个 blog 系统可以 web 端查看,还可以全局查找接口,查看背锅人,版本控制,语法高亮,不要太爽。
    mzeht
        10
    mzeht  
       2017-01-19 22:43:01 +08:00
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1659 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 29ms · UTC 16:48 · PVG 00:48 · LAX 08:48 · JFK 11:48
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.