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

大家现在还用 swagger 生成 API 文档吗

  •  
  •   shadowfish0 · 114 天前 · 2474 次点击
    这是一个创建于 114 天前的主题,其中的信息可能已经有所发展或是发生改变。

    之前我试过纯粹用编辑 API 的软件写 API 文档,但是发现坚持不下去,每个 API 返回值啥的都要我一个个写好,而且接口改动之后往往就忘记了改 API 文档,毕竟是在两个地方的,要开两个软件。

    用了 swagger 感觉会轻松很多,只需要定义传入参数就行了,传出参数也只需要简单描述一下每个字段是干啥的,返回值直接就动态生成了。注释就在代码里,总能比上面这种方法不容易忘吧

    但是现在写着写着又感觉不爽了,遇到复杂的接口,参数很多,注释比代码都长有时候,而且 idea 的 swagger 注释和其他注释一样黄黄的看着人眼都要晃了,突然想到如果能把 swagger 的注释颜色改成普通注释颜色应该会舒服很多,不知道可不可行。

    17 条回复    2021-09-28 23:44:42 +08:00
    liuxu
        1
    liuxu  
       114 天前
    不想写了,现在都是用 postman 做接口文档
    yitingbai
        2
    yitingbai  
       114 天前
    swagger 不好的地方太多了, 有些参数并不想暴露给前端, 另外注解写的太多, 代码又臭又长, 但是除了这个又有啥好办法呢, 我更不想再去维护一份文档
    Philippa
        3
    Philippa  
       114 天前 via iPhone
    现在一般用 grpc 自动生成不用写的就定一下 path 和 method 就完事了,要么是 graphql 也有 playground 。swagger 要是手写的话还不如不要了
    sutra
        4
    sutra  
       114 天前
    RESTful 的话用 enunciate https://github.com/stoicflame/enunciate

    GraphQL 的话,playground 也都能显示文档。
    xuanbg
        5
    xuanbg  
       114 天前   ❤️ 1
    swagger 生成的文档不是自己的文档,所以从来不用。
    shellic
        6
    shellic  
       114 天前
    直接导出 postman 了
    abcbuzhiming
        7
    abcbuzhiming  
       114 天前
    到目前为止,swagger 这种代码和文档直接关联的做法还是最佳实践,单独写文档的最大问题,就是你一定要分出人力监督写代码的人务必更新文档,尤其在协作开发时这个问题非常突出
    napsterwu
        8
    napsterwu  
       114 天前 via iPhone
    Swagger 选择 openapi 3.0 模式,生成的文档可以整个导入 postman, insomnia 之类的客户端,不挺香的
    liaojl
        9
    liaojl  
       114 天前 via iPhone
    @yitingbai 某些参数不想暴露给前端,可以在字段注解上加 ignore=true
    chendy
        10
    chendy  
       114 天前
    swagger 是 code first 不是 api first
    最好还是有独立的 api 管控
    wangbenjun5
        11
    wangbenjun5  
       113 天前
    阿里都是特别 low 的做法,人工手动整理到语雀文档上。。。也没个标准规范!如果时间充分的情况下我觉得人工整理也还行吧,swagger 就是省事
    Rwing
        12
    Rwing  
       113 天前
    还好吧,只是代码的注释而已,就算不用 swagger 也要写,所以没什么不舒服的感觉
    abigeater
        13
    abigeater  
       113 天前
    不喜欢写 swagger 觉得很“笨重”,还不如用 postman 调试时顺便生成的文档。
    EscYezi
        14
    EscYezi  
       113 天前 via iPhone
    还是要用的,前后端联调接口给个链接就行,有效降低沟通成本,写很多注解也就麻烦那一次,之后维护方便点。
    参数多的话直接包一个实体类,每个字段上写 ApiModelProperty 注解
    talen666
        15
    talen666  
       113 天前
    用的 YAPI
    lixm
        16
    lixm  
       113 天前
    openapi 规范的文档, 难道不是用来生成代码的吗? 一个模型上百个字段, 一个个手写?
    MarioLuo
        17
    MarioLuo  
       69 天前 via Android
    用 Yapi X 插件,从 Javadoc 中一键生成文档: https://github.com/jetplugins/yapix
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   4058 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 03:11 · PVG 11:11 · LAX 19:11 · JFK 22:11
    ♥ Do have faith in what you're doing.