V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
The Go Programming Language
http://golang.org/
Go Playground
Go Projects
Revel Web Framework
haierspi
V2EX  ›  Go 编程语言

问一下各位大佬.. 除了 Swagger 还有其他生成 API 文档的东西么?

  •  
  •   haierspi · 2022-09-20 14:21:11 +08:00 · 3362 次点击
    这是一个创建于 793 天前的主题,其中的信息可能已经有所发展或是发生改变。

    Swagger 的文档定义太弱的感觉.. 很多无法定义

    19 条回复    2023-10-14 21:57:28 +08:00
    Terry05
        1
    Terry05  
       2022-09-20 14:29:18 +08:00
    YAPI 、APIFOX
    xiao109
        2
    xiao109  
       2022-09-20 14:40:24 +08:00
    openapi + redoc 。
    LeegoYih
        3
    LeegoYih  
       2022-09-20 15:01:30 +08:00
    什么场景
    charmToby
        4
    charmToby  
       2022-09-20 15:23:30 +08:00
    nekoneko
        5
    nekoneko  
       2022-09-20 17:41:07 +08:00
    @charmToby #4 感觉还不如 Swagger 呢, 好麻烦的样子
    我记得有 IDEA 插件, 无侵入式的
    yhvictor
        6
    yhvictor  
       2022-09-20 17:43:33 +08:00 via iPhone
    实际用了 protobuf 就没这个问题了
    vayci
        7
    vayci  
       2022-09-20 18:46:32 +08:00
    spring 全家桶之 spring-restdocs
    tramm
        8
    tramm  
       2022-09-20 18:59:32 +08:00
    dorna
    tramm
        9
    tramm  
       2022-09-20 18:59:55 +08:00
    @tramm Torna
    silentsky
        10
    silentsky  
       2022-09-20 19:19:53 +08:00 via Android
    apifox
    Benana
        11
    Benana  
       2022-09-21 10:09:52 +08:00
    我一般用 Swagger 的增强,knife4j
    cp19890714
        12
    cp19890714  
       2022-09-21 13:29:26 +08:00
    * yapi
    * easyapi 有 IDEA 插件
    * smart-doc + torna 有 maven 插件,这是我现在在用的

    smart-doc + torna 最大优点是对代码无侵入。
    通过 maven plugin 一键生成文档,上传到 torna ,其他人在 torna 上可以立即看到文档更新。torna 还支持接口调用和 mock 。
    songhaozhi
        13
    songhaozhi  
       2022-09-21 13:41:39 +08:00
    smart-doc 是一款同时支持 java restful api 和 apache dubbo rpc 接口文档生成的工具。完全基于注释生成文档,做到零侵入。

    https://github.com/smart-doc-group/smart-doc
    securityCoding
        14
    securityCoding  
       2022-09-30 11:54:50 +08:00
    @yhvictor protobuf 好评,直接基于 pb 生成 rpc/http 接口代码就行了。
    AxinBlog
        15
    AxinBlog  
       2022-10-17 17:30:22 +08:00
    php
    AxinBlog
        16
    AxinBlog  
       2022-10-17 17:32:51 +08:00
    我去,按个回车就回复了,php 我用 apidoc ,java 我用 knife4j ,公司 apifox
    haierspi
        17
    haierspi  
    OP
       2023-08-03 14:17:32 +08:00
    想集成到 go 的项目里..
    haierspi
        18
    haierspi  
    OP
       2023-08-03 14:17:59 +08:00
    @Terry05 apifox 已经在用了.. 但是要手动去添加
    ricebna
        19
    ricebna  
       2023-10-14 21:57:28 +08:00
    对于接口文档的编写, 我觉得用任何工具都会有极大的效率耗损。包括 yapi ,postman ,还有注释类的 swagger 。
    接口文档特别是内部用的并且是前端用的,95%的情况就是一个简单的输出与输入,主要工作是描述清楚字段结构,主要目的是与前端达成沟通以及存档的作用,并不需要多么标准化。
    而各种工具,无论是界面类的还是注释自动转换类的, 都需要遵照特定规范,按要求去填写。
    点击一个输入框或是写上特定标记注释都需要额外消耗,这些精准规范其实没必要。

    所以我认为在写文档的效率方面, 直接用最简单的文本是最方便的,直接在代码编辑器方法的注释上上这段文本,不需要遵照特定注释规范,无需担心格式出错。特别是输出参数比较多, 层级也多,直接用所见即所得的 json 文本本身做为描述是最简单的。

    然后把我们写得不那么标准的简化注释用 ChatGPT 转换成勉强标准的结构化文档,这样就很好,它就适合做这类不精准的东西,还有纠错能力。
    我试过了,它转换成的 postman 导入文件居然是对的,我还担心这种事情它一般会出错,不过凡涉及代码的东西最好不用,有时出错给它排错的时间不值。

    [Imgur]( )
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2795 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 15:03 · PVG 23:03 · LAX 07:03 · JFK 10:03
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.