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

求推荐一个开源的 API 文档管理系统

  •  
  •   f0101 · 2014-03-31 16:15:48 +08:00 · 52848 次点击
    这是一个创建于 3650 天前的主题,其中的信息可能已经有所发展或是发生改变。
    目前想为项目写一个API文档,在线阅读的。想找一个好用点的API文档管理系统。能实现像微博API、淘宝开放平台这种效果的:

    http://open.weibo.com/wiki/2/statuses/querymid
    http://wiki.open.t.qq.com/index.php/%E5%B9%B3%E5%8F%B0%E4%BB%8B%E7%BB%8D
    http://open.taobao.com/doc/detail.htm?id=101710

    试用了几个感觉都不理想。求推荐。
    34 条回复    2020-09-04 15:42:53 +08:00
    XadillaX
        1
    XadillaX  
       2014-03-31 16:18:09 +08:00
    马克一下。同求!~
    jedyu
        3
    jedyu  
       2014-03-31 16:33:30 +08:00
    stcatz
        4
    stcatz  
       2014-03-31 16:50:54 +08:00
    http://apiblueprint.org

    不过还没深入研究,求试用报告。
    lang1pal
        5
    lang1pal  
       2014-03-31 16:54:19 +08:00
    淘宝的看不出来
    sina和腾讯的是http://www.mediawiki.org/wiki/MediaWiki
    FuryBean
        6
    FuryBean  
       2014-03-31 16:57:41 +08:00
    docular: http://grunt-docular.com
    daux.iohttp://daux.io

    如果还是不满意,可以在metalsmith的基础上自己打造:
    https://github.com/segmentio/metalsmith
    jyhmijack
        7
    jyhmijack  
       2014-03-31 16:58:15 +08:00   ❤️ 1
    不长的文档可以用这个https://github.com/tripit/slate
    coderliss
        8
    coderliss  
       2014-03-31 17:07:16 +08:00
    mark...
    楼主最后选用了哪个?求PK结果。
    cxh116
        9
    cxh116  
       2014-03-31 17:28:21 +08:00
    用sphinx doc应该最省事, 默认模板不好看,自己再写一个

    目前用redmine的wiki在写,因为自带了toc(table of content)标签,用着也还不错


    也看到有人用middleman写文档, http://docs.cloudfoundry.org/ https://github.com/cloudfoundry/cf-docs
    hupohuke
        10
    hupohuke  
       2014-04-01 08:23:06 +08:00
    sphinx
    missdeer
        11
    missdeer  
       2014-04-01 09:09:30 +08:00
    不是用doxygen比较多么
    lygmqkl
        12
    lygmqkl  
       2014-04-01 17:01:46 +08:00
    http://apihelp.yiiblog.info/

    我自己开发了一份,暂时还没开源,因为项目忙 搁置了,如果有需要可以共享一份给你。
    f0101
        13
    f0101  
    OP
       2014-04-02 15:44:13 +08:00
    @lygmqkl 很不错,方便的话发我一份: [email protected]
    f0101
        14
    f0101  
    OP
       2014-04-16 13:20:43 +08:00
    @lygmqkl 老兄看来还是不愿意分享啊
    pheyer
        15
    pheyer  
       2015-02-16 16:38:08 +08:00
    Rico
        16
    Rico  
       2015-06-24 16:20:04 +08:00
    bsbgong
        17
    bsbgong  
       2015-11-04 17:39:06 +08:00
    RAP 很不错,没用过的可以试试
    star7th
        18
    star7th  
       2015-12-01 16:51:05 +08:00
    ShowDoc 是什么

    每当接手一个他人开发好的模块或者项目,看着那些没有写注释的代码,我们都无比抓狂。文档呢?!文档呢?! Show me the doc !!
    程序员都很希望别人能写技术文档,而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版,想着新建的 word 文档放在哪个目录等各种非技术细节。
    word 文档零零散散地放在团队不同人那里,需要文档的人基本靠吼,吼一声然后上 qq 或者邮箱接收对方丢过来的文档。这种沟通方式当然可以,只是效率不高。
    ShowDoc 就是一个非常适合 IT 团队的在线文档分享工具,它可以加快团队之间沟通的效率。
    它可以用来做什么

    API 文档( 查看 Demo )

    随着移动互联网的发展, BaaS (后端即服务)越来越流行。服务端提供 API , APP 端或者网页前端便可方便调用数据。用 ShowDoc 可以非常方便快速地编写出美观的 API 文档。
    数据字典( 查看 Demo )

    一份好的数据字典可以很方便地向别人说明你的数据库结构,如各个字段的释义等。
    说明文档

    你完全可以使用 showdoc 来编写一些工具的说明书,也可以编写一些技术规范说明文档以供团队查阅
    它都有些什么功能

    分享与导出

    响应式网页设计,可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成 word 文件,以便离线浏览。
    权限管理

    公开项目与私密项目
    ShowDoc 上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问,而私密项目则需要输入密码验证访问。密码由项目创建者设置。
    项目转让
    项目创建者可以自由地把项目转让给网站的其他用户。
    项目成员
    你可以很方便地为 ShowDoc 的项目添加、删除项目成员。项目成员可以对项目进行编辑,但不可转让或删除项目(只有项目创建者才有权限)
    编辑功能

    markdown 编辑
    ShowDoc 采用 markdown 编辑器,无论是编辑还是阅读体验都极佳很棒。如果你不了解 Markdown ,请在搜索引擎搜索"认识与入门 Markdown"
    模板插入
    在 ShowDoc 的编辑页面,点击编辑器上方的按钮可方便地插入 API 接口模板和数据字典模板。插入模板后,剩下的就是改动数据了,省去了很多编辑的力气。
    历史版本
    ShowDoc 为页面提供历史版本功能,你可以方便地把页面恢复到之前的版本。
    部署到自己的服务器

    克隆或者下载代码:
    https://github.com/star7th/showdoc
    导入数据库
    下载代码后,将跟目录的 showdoc.sql 文件导入 mysql 数据库
    修改配置文件
    进入 Application/Common/Conf/目录,编辑 config.php 文件,填写相应的数据库信息
    目录权限
    请确保 Application/Runtime 有可写权限
    使用在线的 ShowDoc

    如果你没有自己的服务器,但又想使用 ShowDoc 作为分档分享工具,你可以使用在线的 ShowDoc http://doc.star7th.com
    版权

    ShowDoc 遵循 Apache2 开源协议发布,并提供免费使用。
    版权所有 Copyright © 2015 by star7th http://blog.star7th.com All rights reserved.
    wujunze
        19
    wujunze  
       2016-05-09 19:29:48 +08:00
    apiManager http://git.oschina.net/leunpha/apiManager 这个用来管理接口还是不错的
    funing
        20
    funing  
       2016-08-21 11:07:21 +08:00   ❤️ 1
    推荐一个国内的跟 postman 很像的工具

    http://apizza.cc

    体验很棒,发送请求和 postman 体验差不多,比 postman 更多的是可以一键生成文档。

    更符合国内的浏览习惯。

    更主要是访问速度快。

    我们公司一直在用。
    Eshan
        21
    Eshan  
       2016-08-28 18:27:58 +08:00
    CrapApi :一个由 anjularjs+bootstrap+springMVC 搭建的免费开源的 API 接口、文档管理系统(应用接口管理系统)

    刚开源不久, github 上 fork 已经超过 100 了,用起来感觉非常不错

    演示项目: http://api.crap.cn

    主要功能:
    1.项目管理、模块管理、接口管理、接口版本管理、接口拷贝、接口文档 pdf 下载、模块加密访问、接口在线调试....

    2.数据字典管理、数据字典加密访问...

    3.多管理员、多权限、多角色管理,精准控制每个接口的删改权限

    4.自定义菜单、自定义网站样式,满足你的各种需求

    5.文章管理:说明文档、需求文档、技术实现文档,想怎么分类 CrapApi 都支持

    6.文档留言、错误码管理、接口排序...

    7.DOC 、 PDF 、 TEXT 、 EXCEL 等资源管理,支持版本号控制,文档内容检索,支持无限级目录设置,支持目录密码访问

    8. 操作日志记录、根据日志恢复数据
    zhishizhanghao21
        22
    zhishizhanghao21  
       2016-09-13 09:37:48 +08:00
    多年后台开发,也是最早用的 word ,后来 html 记录。
    不过用起来都不是很爽,市面上其他的开源接口文档管理工具呢,感觉是给自己用的,而不是给前端开发人员用的。
    然后有发现了一个是阿里的 rap 。用了一段时间,挺好的,但是没有在线测试功能。
    然后自己就开发了一个管理工具。
    小幺鸡接口文档管理工具。
    支持 http 、 websocket 在线测试。
    支持 json 、 txt 、 xml 、二进制等数据类型。
    http://www.xiaoyaoji.com.cn/
    可以点进去看看效果怎么样。
    配张图给大家看看
    https://segmentfault.com/img/bVCzZs/view
    zhishizhanghao21
        23
    zhishizhanghao21  
       2016-09-13 09:38:13 +08:00
    @wujunze 地址已经失效了。刚看见换成这个了: http://git.oschina.net/zhoujingjie/apiManager
    wujunze
        24
    wujunze  
       2016-09-13 15:53:31 +08:00
    @zhishizhanghao21 3Q 你这个后台是 java 实现的 我想找个后台是 php 的 我对 php 比较熟 修改也比较方便
    wujunze
        25
    wujunze  
       2016-09-13 15:55:53 +08:00
    @lygmqkl 网站 404 了
    wujunze
        26
    wujunze  
       2016-09-13 15:56:56 +08:00
    @funing http://apizza.cc/ 代码不开源 重要的接口文档不敢放别人服务器啊
    vus520
        27
    vus520  
       2016-10-03 20:59:16 +08:00
    apiManager 和 rap 不错,带管理、测试、文档
    daux 只能算文档功能
    funing
        28
    funing  
       2016-10-20 10:00:20 +08:00
    @wujunze 现在貌似可以离线导出 html 文档了,就当一个文档编辑器用吧。
    ZiLong
        29
    ZiLong  
       2016-10-29 22:44:39 +08:00
    头疼
    zhudelin
        30
    zhudelin  
       2017-01-22 08:10:11 +08:00
    推荐一个 http://helloworld.net.cn 可以视化操作,可导出
    loveskyforever
        31
    loveskyforever  
       2017-05-12 12:09:48 +08:00   ❤️ 1
    什么是 SBDoc ?

    SBDoc 是一个商业化开源产品,完全免费。无论你是前端工程师,还是后端工程师,接口永远都是两者交互的桥梁,所以 SBDoc 专为中小型团队量身打造,旨在解决接口的管理,测试与数据生成,实现真正的一体化解决方案。

    SBDoc 有哪些功能

    1.团队协作,可以对不同的成员分配权限,有两种权限,管理员:可以增删改查项目和接口信息。观察者:可以查看,测试,mock 接口数据,但是不能修改接口和项目的信息。

    2.编写接口文档,摒弃了传统的纯文本编写方式,采用可视化编写,随意拖拽,可以添加任意层次信息,支持 JSON 入参格式,并且实时预览文档编写结果。

    3.对接口进行测试,对于外网测试,没有跨域,后台采用的是 proxy 代理,对于内网,需要在本地安装 node 环境,然后下载系统内提示的 net.js 文档,在本地用 node 运行即可。net.js 就是一个 http,https 的透明代理。

    4.自动生成接口,很多时候,我们的后端开发人员都是先将接口开发好,再去写接口文档的,或者是接口有比较大的改动,接口文档也要改动很多。对于这种情况,可以在测试接口后对接口的文档信息进行一键自动生成,接口的所有入参,出参,http 头都会自动生成到文档,我们要做的就是简单的修修改改就可以啦

    5.可以对接口进行自动化测试,采用原生的 js 编写少量代码便可以对接口进行高效智能的测试,业内独创 web 端自动化测试技术!

    6.对数据进行无缝 mock,在大部分情况下,前端的开发人员都是要等待后端的开发者将接口开发调试好才能进行下一步开发,这样会耗费大量的时间精力,如果要本地生成数据那么成本也会比较高,所以 SBDoc 有独特的无缝 mock 技术,只需要在本地用 node 运行 net.js ,加上 mock server 地址(每个项目都会自动生成自己的 mock Server 地址)和你需要请求的真实地址,当您的接口文档的状态为开发完成的时候,net.js 不会去请求 mock server 地址而去请求真实地址(举例:node net.js http://sbdoc.cn:10000/mock/586b17545fa2d311c0915021 http://localhost:8081) ,然后将您开发工程下的根 url 替换为 localhost:36742 即可开启您的 Mock 之旅!

    产品文档

    http://sbdoc.cn
    SBDoc 开源

    本次开源的是 SBDoc 的内网版本,可以直接部署到内网中,和线上版本在功能上是完全一样的,区别在于:

    1.线上的系统用了前端和后端两套工程,并且用 nginx 做了负载均衡,redis 做缓存,而内网版本合并为一个工程,直接用 node 做静态服务器,取消了缓存,这样对于很多中小型团队来说很轻便而且也够用了。

    2.线上系统在安全性方面做了不少加固处理,而内网版本默认内网是安全的,也为了提高 node 作为服务器的效率,取消了很多加固处理,如果用户有需要可以自行添加。

    如何部署

    1.首先本地要安装 node 环境,推荐 6.10.0 版本(下载页面)

    2.安装 mongodb(下载页面),可使用 robomongo 来作为 mongodb 的客户端工具(下载页面),启动 mongodb 后(如何启动),用 robomongo 来连接,新建一个 database 作为 SBDoc 的数据库(名称随意)

    3.将 SBDoc 的源码 down 到本地,进入根目录,修改 config.json

    {
    "db":"mongodb://localhost:27017/SBDoc", //这里为你的 mongodb 服务器的地址和库的名称
    "filePath":"/Users/Shared/SBDoc", //这里作为 SBDoc 文件上传的路径
    "imgPath":"/Users/Shared/SBDoc/img", //这里是 SBDoc 图片上传的路径(是 SBDoc 文件上传的路径的直接子目录) "tempPath":"/Users/Shared/SBDoc/temp", //这里 SBDoc 临时文件上传的路径(是 SBDoc 文件上传的路径的直接子目录) "port":10000, //SBDoc 启动的端口号
    "version":"1.0.0" //SBDoc 的版本号(无需修改)
    }

    4.在命令行下运行 node SBDoc 的根目录 /SBDoc/bin/www 即可启动 SBDoc (如果是 windows 环境下,请修改目录分隔符),在浏览器里输入 localhost:SBDoc 启动的端口号,出现首页表示部署成功。

    问题反馈

    如果你有任何问题和建议,请在 issues 里面指出,每个月的 1 号和 15 号会发布功能迭代版本,根据 bug 情况不定期的会发布 bug 迭代版本。如果你想加入开源的大家庭,欢迎加入 qq 群:611940610
    vocalman
        32
    vocalman  
       2017-11-23 17:45:06 +08:00
    几年的开发,接口管理工具市面上我也用过很多了,有些的确如同楼主说的不好用
    后来找到 eoLinker,我觉得目前最好用的,目前公司团队都在用,推荐给楼主。
    eoLinker:[https://www.eolinker.com]( https://s.growingio.com/gNKZYz),必须说的是 eoLinker 开源免费的。
    下面我复制一些产品的开源项目和链接:
    开源支持:[https://www.eolinker.com/#/os/download]( https://www.eolinker.com/#/os/download)
    Github:[https://github.com/eolinker]( https://github.com/eolinker)
    码云:[https://gitee.com/eoLinker-API-Management]( https://gitee.com/eoLinker-API-Management)
    Coding:[https://coding.net/u/eolinker/project]( https://coding.net/u/eolinker/project)
    Blog:[http://blog.eolinker.com]( http://blog.eolinker.com
    视频教程:[http://blog.eolinker.com/#/course/]( http://blog.eolinker.com/#/course/)
    推荐你去用一下。
    balabalaguguji
        33
    balabalaguguji  
       2018-12-27 14:22:12 +08:00
    国内外的我也都用过,推荐你试下: https://easydoc.xyz
    andychen1
        34
    andychen1  
       2020-09-04 15:42:53 +08:00
    那我推荐 api-mom
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5207 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 01:22 · PVG 09:22 · LAX 18:22 · JFK 21:22
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.