V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
推荐学习书目
Learn Python the Hard Way
Python Sites
PyPI - Python Package Index
http://diveintopython.org/toc/index.html
Pocoo
值得关注的项目
PyPy
Celery
Jinja2
Read the Docs
gevent
pyenv
virtualenv
Stackless Python
Beautiful Soup
结巴中文分词
Green Unicorn
Sentry
Shovel
Pyflakes
pytest
Python 编程
pep8 Checker
Styles
PEP 8
Google Python Style Guide
Code Style from The Hitchhiker's Guide
firiceguo
V2EX  ›  Python

Django 的 API 文档问题

  •  1
     
  •   firiceguo · 2019-04-10 15:48:20 +08:00 via Android · 2982 次点击
    这是一个创建于 2088 天前的主题,其中的信息可能已经有所发展或是发生改变。

    项目是用的 Django 和 drf,最早的 API 文档考虑的是代码里面写注释,然后用 Sphinx 自动生成文档,所以注释的格式都是 Google 的。

    后来和前端交流前端表示看那个文档和看代码差不了多少,更希望用能发送请求的工具,然后各种工具迭代现在整个大组在推 swagger,swagger 看起来确实好用,但是要改过去我查了查好像就要重写全部的接口注释,或者用 coreapi,工作量好像很大。

    由于项目比较大,各种接口和参数修改也挺频繁,重写注释比较困难,想请问一般大家遇到这种情况都是怎么做的,我们这种情况有没有什么简便的方法。感谢各位大佬了。

    13 条回复    2019-04-11 10:18:05 +08:00
    huisezhiyin
        1
    huisezhiyin  
       2019-04-10 16:34:13 +08:00
    文档的话 我们以前是用一个接口工具 就写一下路由 请求的参数和响应的结果
    文档和注释这种东西没有办法 手撸是最好的
    apizza 可以试试
    firiceguo
        2
    firiceguo  
    OP
       2019-04-10 16:44:06 +08:00 via Android
    @huisezhiyin 感谢,我去看看
    janxin
        3
    janxin  
       2019-04-10 16:50:34 +08:00
    文档注释确实没有办法,换到标准格式只能重写
    est
        4
    est  
       2019-04-10 16:59:24 +08:00
    swagger 有个 restframework 套件~~~改一改勉强能用。
    TommyLemon
        5
    TommyLemon  
       2019-04-10 17:10:30 +08:00
    /
    TommyLemon
        6
    TommyLemon  
       2019-04-10 17:14:04 +08:00
    自动化接口管理工具,支持自动生成文档与注释、自动生成代码、自动化回归测试、自动静态检查等。
    独立的接口管理工具,对代码没有任何侵入性:

    自动生成接口文档,清晰可读永远最新
    自动生成请求代码,支持 Android 和 iOS
    自动生成 JavaBean 文件,一键下载
    自动管理与测试接口用例,一键共享
    自动给请求 JSON 加注释,一键切换
    自动保存历史请求记录,一键恢复
    自动校验与格式化 JSON,支持高亮和收展

    创作不易,GitHub 右上角点 Star 支持下吧 ^_^
    https://github.com/TommyLemon/APIJSONAuto

    这个平台还提供额外的 [机器学习自动化测试]
    http://apijson.org/
    TommyLemon
        7
    TommyLemon  
       2019-04-10 17:21:33 +08:00
    不需要在后端工程写任何 代码、注释、注解 等,
    支持自动查数据库表和字段属性作为文档和注释,
    也支持在请求 JSON 里手动写行注释、段注释,
    输入 URL 和请求 JSON > 点 发送请求 按钮测试接口 > 点右上角共享图标按钮 > 输入接口名 > 点上传按钮
    就行了
    firiceguo
        8
    firiceguo  
    OP
       2019-04-10 18:15:11 +08:00 via Android
    @janxin 哎没错,之前也迁移过好几次,感觉太繁琐了
    firiceguo
        9
    firiceguo  
    OP
       2019-04-10 18:15:56 +08:00 via Android
    @TommyLemon 看起来不错,感谢
    wisetc
        10
    wisetc  
       2019-04-10 23:44:04 +08:00 via iPhone
    djangorestfulframework 不是有很好的调试工具吗,为什么还要写单独的文档呢?
    TommyLemon
        11
    TommyLemon  
       2019-04-11 10:07:22 +08:00
    @firiceguo 哈哈,可以点 Star 支持下哦 ^_^
    firiceguo
        12
    firiceguo  
    OP
       2019-04-11 10:10:03 +08:00 via Android
    @wisetc 调试还行,就是有不少参数的含义光看接口不清楚,有文档还是好一点
    xixijun
        13
    xixijun  
       2019-04-11 10:18:05 +08:00
    drf 可以自动生成 API 文档
    url(r'^docs/', include_docs_urls(
    title='API Documentation',
    renderer_classes=(CustomRenderer,),
    permission_classes=(IsAdminUser,)
    )),
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   954 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 19ms · UTC 21:36 · PVG 05:36 · LAX 13:36 · JFK 16:36
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.