有没有觉的 swagger2 注解难用的,用注释生成文档不好么? - V2EX
V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
Rogeryxx
V2EX    Java

有没有觉的 swagger2 注解难用的,用注释生成文档不好么?

  •  1
     
  •   Rogeryxx
    iamyours 2020-09-14 09:16:11 +08:00 5868 次点击
    这是一个创建于 1860 天前的主题,其中的信息可能已经有所发展或是发生改变。

    接口开始使用 Swagger2 生成文档,每个 Controller 都要配一堆注解生成文档,繁琐重复。就比如我写了如下的 Controller:

    @Api(tags = "学生接口") @RestController @RequestMapping("web/v1/student") public class StudentController { @ApiOperation("根据编号获取学生信息") @ApiImplicitParams( @ApiImplicitParam(name = "stu_no", value = "学生编号")) @GetMapping("getByNo") public StudentVO getByNO(@RequestParam("stu_no") String stuNo) { StudentVO stu = new StudentVO(); stu.setStuNo(stuNo); stu.setName("张三"); return stu; } @ApiOperation("添加学生信息") @ApiImplicitParams( { @ApiImplicitParam(name = "name", value = "学生名称", defaultValue = "张三"), @ApiImplicitParam(name = "no", value = "学生编号", defaultValue = "std-10001", required = true) } ) @PostMapping("add") public StudentVO addStudent(String name, String no) { StudentVO s = new StudentVO(); s.setName(name); s.setStuNo(no); return s; } } 

    我觉得更简便的方式是通过注释生成文档,就像这样:

    /** * 学生接口 */ @RestController @RequestMapping("web/v1/student") public class StudentController { /** * 根据编号获取学生信息 * @param stuNo 学生编号 */ @GetMapping("getByNo") public StudentVO getByNO(@RequestParam("stu_no") String stuNo) { StudentVO stu = new StudentVO(); stu.setStuNo(stuNo); stu.setName("张三"); return stu; } /** * 添加学生信息 * @param name 学生名称|张三 * @param no 学生编号|required|std-10001 */ @PostMapping("add") public StudentVO addStudent(String name, String no) { StudentVO s = new StudentVO(); s.setName(name); s.setStuNo(no); return s; } } 

    于是我写了个EasySwagger,只需加个@EnableEasySwagger开启功能。原理也简单,通过反射修改DocumentationCache类中的文档信息。

    32 条回复    2021-07-22 22:43:59 +08:00
    lyusantu
        1
    lyusantu  
       2020-09-14 09:22:18 +08:00
    不用 Swagger,每个 Controller 不还是需要写一堆注释? 看起来不也是重复且行数更长

    照这样认为的话,自己完全可以再写一个自定义注解 CustomRestController,把 RestController 和 RequestMapping 整合一下,用起来 @CustomRestController("/web/v1/student")更简单
    Rwing
        2
    Rwing  
       2020-09-14 09:22:53 +08:00
    用注释生成文档竟然不是标准功能。。。。。
    Vkery
        3
    Vkery  
       2020-09-14 09:30:26 +08:00
    用注释的话大家都要用标准的注释模板,而且字段说明和参数示例都得通过统一的格式来写,注释里一般都没有提示容易写错
    pushback
        4
    pushback  
       2020-09-14 09:32:36 +08:00
    所以说反射里面有获取类注释的
    anzu
        5
    anzu  
       2020-09-14 09:42:36 +08:00
    为什么不直接用 @ ApiParam
    chendy
        6
    chendy  
       2020-09-14 09:44:18 +08:00
    注释出文档问题不大
    出 openapi 格式问题很大,很多东西是覆盖不到的
    qwerthhusn
        7
    qwerthhusn  
       2020-09-14 10:12:38 +08:00
    我感觉这个侵入有点烦,还不好生成离线文档,有的生成得文档还不准确,倒不如分开写
    zoyua
        8
    zoyua  
       2020-09-14 10:16:48 +08:00
    个人觉得 swagger 注解的内容可以部分替代掉注释
    cweijan
        9
    cweijan  
       2020-09-14 10:33:28 +08:00
    这个项目可以满足你的需求
    https://github.com/Willing-Xyz/RestDoc
    NakeSnail
        10
    NakeSnail  
       2020-09-14 10:39:33 +08:00
    是有点烦,只是标准的注释格式现在的表达能力还不够,到最后还是要自己定义一些格式。Swagger 这方面已经很完善了
    wc951
        11
    wc951  
       2020-09-14 10:45:10 +08:00 via Android
    swagger 侵入性太强,我一般用基于 spring test 的 spring restdocs
    passerbytiny
        12
    passerbytiny  
       2020-09-14 11:03:27 +08:00 via Android
    重要的第一点,接口文档是给全体开发人员用的,Javadoc 是给 Java 开发人员用的,这一点不同导致的就是“约定”的不同。

    第二点,相比与注解,Javadoc 规则好多年没升级了,而且 Javadoc 是注释不是代码,并不适合自动化处理。Hibernate 、Spring 都已经嫌 @Deprecated 不够用开始自己造仅当标记的注解了。

    第三点,严格来说,Controller 中的公开方法,是给框架用的模板,而不是给其他方法调用的 api,给他附加 Javadoc 是不合适的。


    解决方案是,接口上不要添加 Javadoc,只用注解。
    passerbytiny
        13
    passerbytiny  
       2020-09-14 11:15:36 +08:00 via Android   1
    @RequestMapping 、 @EventListerer 、 @Bean 等注解加持的方法,事实上都不是对外 API,都不需要再加 Javadoc 。奈何过不了 Checkstyle,我现在用是统一加“已忽略,请看它的注解”的 Javadoc,不知道有没有更好的方案。

    @wc951 这个虽不侵入代码,但侵入开发方式。它主要是接口的测试代码,导出 api 是附带功能,适合测试驱动开发团队,不适合大多数团队。
    NeverNot
        14
    NeverNot  
       2020-09-14 11:21:50 +08:00
    我现在 觉得 swagger 集成进项目里面 太耦合了,一个 controller 方法,注解 行数比代码行数还多, 打包的时候 多一堆 jar 包,用了 一次 yapi 后,觉得 接口文档 就该和 业务项目分离, 文档是文档 项目是项目,两边清爽
    SD10
        15
    SD10  
       2020-09-14 11:25:39 +08:00 via iPhone
    一个开发前,一个开发后,目标不一样
    star7th
        16
    star7th  
       2020-09-14 11:56:33 +08:00
    我觉得 sw 那种方式太侵入代码了,不是一种好方式。当然国外和国内情况有点不一样。
    就国内的场景而言,这种方法并不使用广泛。
    star7th
        17
    star7th  
       2020-09-14 12:01:55 +08:00
    所以我支持了另一种没那么侵入业务代码的注解生成机制: https://www.showdoc.com.cn/page/741656402509783
    clf
        18
    clf  
       2020-09-14 12:31:27 +08:00
    apidoc,非侵入+注释写文档。
    xnotepad
        19
    xnotepad  
       2020-09-14 12:47:41 +08:00
    要不要试试 https://apidoc.tools 就是注释写文档,还提供了对 vscode 的插件支持。
    JJstyle
        20
    JJstyle &nsp;
       2020-09-14 13:17:52 +08:00
    我都是手写模板,没觉得有多麻烦,这是我 API 模板: https://textit.yeskn.com/b49f63e35a6b09d3d947966cf18a4ef9
    lidlesseye11
        21
    lidlesseye11  
       2020-09-14 13:34:26 +08:00
    我以为一般都是手写 swagger 文档再拿去生成代码(生成的代码应该是和 swagger 没关系的),而不是在代码里写文档去生成 swagger 。。。
    (虽然有点儿像鸡生蛋蛋生鸡。。不过这样搞总觉得哪里不对劲儿
    z00z
        22
    z00z  
       2020-09-14 13:46:50 +08:00
    Swagger2 的.NET 版就支持直接根据注释生成接口文档
    balabalaguguji
        23
    balabalaguguji  
       2020-09-14 17:26:40 +08:00
    注释写文档比较麻烦,而且还会把代码弄的乱七八糟一堆额外的东西。
    可以试下易文档 https://easydoc.xyz 有专门的 API 文档编辑器,方便很多

    看个预览效果:www.easydoc.xyz/s/17790664
    liujialongstar
        24
    liujialongstar  
       2020-09-14 17:39:43 +08:00
    @lyusantu 公司有一项考核指标: 千行代码注释, 如果不用 swagger 正好可以刷指标
    zzzmh
        25
    zzzmh  
       2020-09-14 17:48:05 +08:00
    apidoc 好像可以满足这个需求
    jeffh
        26
    jeffh  
       2020-09-14 17:50:45 +08:00
    yapi 就可以注释生成文档啊
    Yuicon
        27
    Yuicon  
       2020-09-14 17:57:26 +08:00
    文档就是要耦合 离代码越近越好 文档与代码不一致或者同步不自动化才是大问题
    jiyingze
        28
    jiyingze  
       2020-09-14 18:33:50 +08:00
    无需额外注解的 SpringBoot API 文档生成工具
    https://japidocs.agilestudio.cn/#/zh-cn/
    静态源代码分析生成文档
    lingxi27
        29
    lingxi27  
       2020-09-14 20:49:42 +08:00
    swagger 文档>>>代码
    ideaa
        30
    ideaa  
       2020-09-15 09:21:27 +08:00
    @cp_api get, /main/index, 获取框架当前版本号
    @cp_request t|当前时间|1

    php 中我这样实现的,仅支持 GET 请求,地址是 /main/index, 接受当前时间参数 t,不能为空
    RandomJoke
        31
    RandomJoke  
       2020-09-22 18:35:48 +08:00
    我也觉得写注释好,比较纯粹。二次开发了一个 restdoc repo,从 javadoc 生成了文档,apidoc 的话也可以,有点学习成本
    smartdoc647
        32
    smartdoc647  
       2021-07-22 22:43:59 +08:00
    spring 技术栈 smart-doc+torna 才是王道
    关于     帮助文档     自助推广系统     博客     API     FAQ     Solana     2793 人在线   最高记录 6679       Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 25ms UTC 07:04 PVG 15:04 LAX 00:04 JFK 03:04
    Do have faith in what you're doing.
    ubao msn snddm index pchome yahoo rakuten mypaper meadowduck bidyahoo youbao zxmzxm asda bnvcg cvbfg dfscv mmhjk xxddc yybgb zznbn ccubao uaitu acv GXCV ET GDG YH FG BCVB FJFH CBRE CBC GDG ET54 WRWR RWER WREW WRWER RWER SDG EW SF DSFSF fbbs ubao fhd dfg ewr dg df ewwr ewwr et ruyut utut dfg fgd gdfgt etg dfgt dfgd ert4 gd fgg wr 235 wer3 we vsdf sdf gdf ert xcv sdf rwer hfd dfg cvb rwf afb dfh jgh bmn lgh rty gfds cxv xcv xcs vdas fdf fgd cv sdf tert sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf shasha9178 shasha9178 shasha9178 shasha9178 shasha9178 liflif2 liflif2 liflif2 liflif2 liflif2 liblib3 liblib3 liblib3 liblib3 liblib3 zhazha444 zhazha444 zhazha444 zhazha444 zhazha444 dende5 dende denden denden2 denden21 fenfen9 fenf619 fen619 fenfe9 fe619 sdf sdf sdf sdf sdf zhazh90 zhazh0 zhaa50 zha90 zh590 zho zhoz zhozh zhozho zhozho2 lislis lls95 lili95 lils5 liss9 sdf0ty987 sdft876 sdft9876 sdf09876 sd0t9876 sdf0ty98 sdf0976 sdf0ty986 sdf0ty96 sdf0t76 sdf0876 df0ty98 sf0t876 sd0ty76 sdy76 sdf76 sdf0t76 sdf0ty9 sdf0ty98 sdf0ty987 sdf0ty98 sdf6676 sdf876 sd876 sd876 sdf6 sdf6 sdf9876 sdf0t sdf06 sdf0ty9776 sdf0ty9776 sdf0ty76 sdf8876 sdf0t sd6 sdf06 s688876 sd688 sdf86