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

关于 swagger 的疑惑

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

    按理来说 openAPI 的 schema 应该先设计好, 然后生成 swagger ui, 但是现在 Java 用注解生成 openAPI 是不是本末倒置?

    19 条回复    2024-06-06 11:02:43 +08:00
    julyclyde
        1
    julyclyde  
       192 天前   ❤️ 1
    1 这事其实和 java 没啥关系
    2 初版 API 规范用注解来生成其实也没什么不合适的,只要别改来改去就可以
    lolizeppelin
        2
    lolizeppelin  
       192 天前   ❤️ 2
    这本质是一个工程问题
    方式 1: 设计人员设计好结构, 接口, 编写文档,由设计指导代码编写
    方式 2: 开发人员编写代码后,同步文档

    1 和 2 的本质区别,在于结构、接口、文档是开发人员负责还是专门的部门、人员负责

    如果根本不存在一个专门部门或者人员负责文档和结构设计,自然倾向于自动生成文档和结构

    注解生成只是自动生成的方式
    bxb100
        3
    bxb100  
    OP
       192 天前
    @julyclyde @lolizeppelin 我不是说这个行为对或者错, 而是在于写 spec 的过程是一个思考的过程, 比如说如何分类, 如何复用, 如何验证. 直接用注解生成一个是有侵入性, 第二个 UI 也不美观, 第三个是写接口的时候突出一个随意, 没有文档, 没有思考过程.

    有没有专门 doc developer 来做和这个事情值不值得做是两个问题, 我主要是想问大家是怎么看待这个事情, 或者有啥其它的真知灼见
    julyclyde
        4
    julyclyde  
       192 天前
    @bxb100 无法实现的理想,不能叫工程理想
    bxb100
        5
    bxb100  
    OP
       192 天前
    @julyclyde #4 确实, 不过我在重新找回理想的过程中
    hoko1814
        6
    hoko1814  
       192 天前
    我理解成那个 swagger 了,溜……
    lolizeppelin
        7
    lolizeppelin  
       192 天前   ❤️ 1
    @bxb100
    你说的没错, spec 和接口的设置本身就是要适配需求、甚至要预留未来需求,本身就是需要比一般代码人员更熟悉的人来编写的

    但是实际项目中,根本没人、或者根本没时间干这个事, 大部分时间都再怼业务代码、需求还改来改去导致接口与结构都一直在变化

    这种情况下还把文档、结构和代码分开,那么反而会成为累赘,还不如写什么代码就生成什么文档和结构


    这种反向自动生成行为本身就是为了适应环境的结果,是结果,不是目的

    你要知道更差劲的结果是: 设计的文档、结构、接口和代码根本对不上、因为根本没人管
    iyiluo
        8
    iyiluo  
       192 天前   ❤️ 1
    开发过程中接口变动很常见,按部就班开发是非常理想化的设想,在现实中几乎不可能
    bxb100
        9
    bxb100  
    OP
       192 天前
    @lolizeppelin #7 多谢回复
    leegradyllljjjj
        10
    leegradyllljjjj  
       192 天前
    年轻人还在这儿研究茴字儿的写法,部门领导 pm 只会关心什么时候能上线
    siteshen
        11
    siteshen  
       192 天前
    如果 spec 能方便地增量生成后端代码框架,先定义 spec 也不会造成额外的负担。而实际上,先设计 schama ,后端要做的是按照设计的 schema 重新用代码实现一遍 input, output, validation ,增加无谓的重复工作。

    所以我选择倾向于用第二种方式,对增量的 API 开发更友好。

    利益相关:后端开发。
    julyclyde
        12
    julyclyde  
       192 天前
    @siteshen spec 可以生成后段代码框架啊。很容易的
    openapi generator
    susuper
        13
    susuper  
       192 天前
    swagger-codegen 可以生成 ts 、java 等前后端代码,前后端都可以写 SPEL ,然后利用工具生成各自接口层,前端实现调用方法,后端实现继承接口。
    chuck1in
        14
    chuck1in  
       192 天前
    先做 spec 再实现这种方式也不是不行,不过有个问题,就是他对整体效率和工程质量的把控上是否有更大的提升。
    有的话,我觉得就可以搞,如果没有的话,就不一定要搞。
    大家怎么看呢。
    bxb100
        15
    bxb100  
    OP
       191 天前
    @chuck1in 类比于 apache 之类的项目都是先写 RFC 然后再开发的流程非常好, 但是我实际去做就挺不好的, 没啥配合度, 感觉就自己一个人玩
    julyclyde
        16
    julyclyde  
       191 天前
    @bxb100 apache 这个例子恐怕不正确吧
    houzhiqiang
        17
    houzhiqiang  
       191 天前
    FastAPI 先写接口定义(方法签名)然后就可以生成 openapi 了,部署到测试环境,接下来补充实现
    @router.get("/users", name="get user")
    def get_user(id: int) -> User:
    # TODO: do something ...
    return User(name="u", )
    siteshen
        18
    siteshen  
       191 天前
    @julyclyde 主要是对「增量」不友好。
    smartdoc647
        19
    smartdoc647  
       168 天前
    线设计 API 文档和工具并不冲突,比如我最近的开发方式:
    1 、分析需求文档
    2 、用自己开发的 SpringBoot 脚手架创建一个空的 SpringBoot 项目用于建模 API 接口
    3 、思考需求,在 2 步骤创建的 API 建模项目中定义空结构体和空 Controller 接口
    4 、用 smart-doc 扫描定义的空接口生成 API 文档
    5 、用生成的 API 文档和前端和产品人员完成定稿和微调。
    6 、启动正式项目开发,完全复制一些前面编写空接口的结构体。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   5763 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 61ms · UTC 01:52 · PVG 09:52 · LAX 17:52 · JFK 20:52
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.