V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
yellowV2ex
V2EX  ›  程序员

大家前后端的接口文档一般用什么写?

  •  
  •   yellowV2ex · 2014-07-22 01:07:45 +08:00 · 29061 次点击
    这是一个创建于 3538 天前的主题,其中的信息可能已经有所发展或是发生改变。
    我是前台(Flash,iOS)目前是用markdown写导出html给PHP们看,列明每条接口的PHP名字,传入什么参数,返回什么内容之类。
    大概是这样子的一个东西,http://coonlab.com/ahhapuzzle_api.html

    虽说用起来不错,但觉得是不是有专门的工具去干这个事情的,你们跟后台定义接口的时候的文档是用什么工具写的?
    (因为前台需求是主导,所以不可以用后台直接生成的那种接口文档,因为首先要告诉他们我需要返回什么样的数据,而不是他们自己去定返回什么给我)
    24 条回复    2019-02-21 14:50:40 +08:00
    churchmice
        1
    churchmice  
       2014-07-22 02:16:30 +08:00 via Android
    有敏感词唉
    yellowV2ex
        2
    yellowV2ex  
    OP
       2014-07-22 02:46:14 +08:00
    @churchmice 哪里哪里
    jsq2627
        3
    jsq2627  
       2014-07-22 04:08:14 +08:00
    TangMonk
        4
    TangMonk  
       2014-07-22 08:23:22 +08:00
    http://apiblueprint.org/

    楼主不如看下这个,
    zhouzm
        5
    zhouzm  
       2014-07-22 08:53:21 +08:00   ❤️ 1
    写文档推荐 sphinx(sphinx-doc.org),开源项目可以用 readthedocs.org 托管文档。

    如果是内部开发,也可以自建 readthedocs 服务器 + git/svn
    sxd
        6
    sxd  
       2014-07-22 09:22:46 +08:00
    为什么是前台写文档给后台 接口不是后台定么?
    ijse
        7
    ijse  
       2014-07-22 09:42:23 +08:00
    http://apiary.io/ 这个挺不错的,用的也是api blue print
    yellowV2ex
        8
    yellowV2ex  
    OP
       2014-07-22 09:54:09 +08:00
    @sxd 先出的设计,然后前台就按照设计做,根据设计的字段定义需要的接口内容,所以前台是主导,要是后台去写的话,后台还要去研究设计和页面跳转什么的,比较麻烦。

    @TangMonk @zhouzm @ijse 谢谢推荐,我去试试看
    @jsq2627
    Mutoo
        9
    Mutoo  
       2014-07-22 10:13:15 +08:00
    vimeo已经被认证好多年了,真理部不喜欢这群搞艺术的,特别是有想法的搞艺术的。
    Mutoo
        10
    Mutoo  
       2014-07-22 10:13:50 +08:00
    @Mutoo 不好意思,穿越帖子了
    oa414
        11
    oa414  
       2014-07-22 10:31:04 +08:00
    LZ试试这个东西, https://helloreverb.com/developers/swagger

    根据代码和注释自动生成文档,还可以在线调试。。
    lynnlee
        12
    lynnlee  
       2014-07-22 11:19:34 +08:00
    我以为都用word呢
    erse
        13
    erse  
       2014-07-22 12:07:10 +08:00
    dokuwiki
    zouxcs
        14
    zouxcs  
       2014-07-22 16:17:45 +08:00
    现在文档都走高端路线了,想当年写word文档到吐啊
    lidl
        15
    lidl  
       2014-10-23 11:58:21 +08:00
    我需要本地编写api文档 ,并导出pdf或html
    用什么 工具 ,求教。
    yellowV2ex
        16
    yellowV2ex  
    OP
       2014-10-23 21:32:47 +08:00
    @lidl Markdown,写好了找个工具导出PDF或html,我现在就是
    errun
        17
    errun  
       2014-11-14 15:41:21 +08:00
    @yellowV2ex 我也是用markdown,但是现在感觉markdown还是比较适合用来写文章,用来写接口文档太累了,毕竟接口文档实际上有个基本的格式的,写接口文档的工具应该只用关心填写内容就好了,不必去关心格式。。
    pheyer
        18
    pheyer  
       2015-02-16 16:13:26 +08:00
    发现了一个好工具RAP,阿里内部使用的,也许对大家有用,介绍可以参考http://div.io/topic/642,接口自动化工具RAP的设计思路
    宣传片:v.youku.com/v_show/id_XNjk5NjMxODA4.html
    官网: http://thx.github.io/RAP/index_zh.html
    源码: https://github.com/thx/RAP
    入门视频:thx.github.io/RAP/study.html
    部署RAP服务的文档: https://github.com/thx/RAP/wiki/deploy_manual_cn
    zhishizhanghao21
        19
    zhishizhanghao21  
       2016-09-01 17:59:29 +08:00
    小幺鸡,简单好用的在线接口文档管理系统
    支持在线测试,经测试(可降低接口错误率)。
    支持 json , js , websocket ,二进制测试。
    支持 restful 接口。
    zhishizhanghao21
        20
    zhishizhanghao21  
       2016-09-01 17:59:47 +08:00
    jsq2627
        21
    jsq2627  
       2017-03-09 12:54:47 +08:00
    穿越一下,回个老帖子。

    最近正好在解决文档问题,做了 test2doc.js 这个文档生成工具,个人认为非常好用。

    https://github.com/stackia/test2doc.js

    使用案例:/t/346019
    jsq2627
        22
    jsq2627  
       2017-03-09 12:55:10 +08:00
    @jsq2627 #21 链接坏了。重发一下: https://www.v2ex.com/t/346019
    balabalaguguji
        23
    balabalaguguji  
       2019-01-22 22:13:36 +08:00
    强烈推荐你 https://easydoc.xyz
    balabalaguguji
        24
    balabalaguguji  
       2019-02-21 14:50:40 +08:00
    @yellowV2ex 你这种编写接口文档太低效了,推荐你 easydoc.xyz ,体验无敌
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3632 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 35ms · UTC 04:33 · PVG 12:33 · LAX 21:33 · JFK 00:33
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.