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

Rogeryxx 12天前 7

接口开始使用 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类中的文档信息。

最新回复 (30)
  • lyusantu 10天前
    引用 2
    不用 Swagger,每个 Controller 不还是需要写一堆注释? 看起来不也是重复且行数更长

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

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

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


    解决方案是,接口上不要添加 Javadoc,只用注解。
  • passerbytiny 10天前
    引用 14
    @RequestMapping 、 @EventListerer 、 @Bean 等注解加持的方法,事实上都不是对外 API,都不需要再加 Javadoc 。奈何过不了 Checkstyle,我现在用是统一加“已忽略,请看它的注解”的 Javadoc,不知道有没有更好的方案。

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

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

    php 中我这样实现的,仅支持 GET 请求,地址是 /main/index, 接受当前时间参数 t,不能为空
  • 游客
    32
返回