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

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

  •  
  •   shadowfish0 · 2021-08-15 00:42:06 +08:00 · 4477 次点击
    这是一个创建于 957 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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