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

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

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

    接口开始使用 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  
       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,不能为空
    jokefaker
        31
    jokefaker  
       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   ·   我们的愿景   ·   实用小工具   ·   2669 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 29ms · UTC 15:31 · PVG 23:31 · LAX 08:31 · JFK 11:31
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.