Java接口文档，用注释还是注解?（java接口文档内容详解）

接口文档 VS 注解

1. 用注释还是注解？swagger 侵入性是不是太强了？从 4 个方面进行打分，满分 100 分。看看接口文档用注释和注解哪个更优秀？

- 第一项是侵入性。注释：它的侵入性很低，因为本身接口和字段也是要写注释的，所以给它打分 95 分。注解它的侵入性稍微强一点，首先要引入 swagger 或者是 knife4j 之类的依赖，然后要写注解，这个就算是一些额外的操作了，给它打分 70 分。

- 再来看功能。注释：它只能导出使用，比如把它导入到 YAPI 或者是 Postman、Apifox 等给它打分 70 分。swagger：

- 第一，它是可以导出的，也是支持 YAPI、Postman、Apifox 等这些主流的工具。

- 第二，是可以本地调试，就是它运行起来之后直接就可以在页面上测试了。knife4j 跟 swagger 的注解是一样的，它的页面更加清爽。

- 第三，很方便的功能，就是提供 API 是特别的方便的，比如说后端在提供 API 的时候，如果是注释，那么编译之后就没有了，但是如果是注解，它就是还存在的，所以就很方便。

- 第四，就是它的实时性很强，可以完整地获取正在运行的应用的接口信息，但注释就很可能是没有更新的。综上所述，给注解的打分是 95 分。

- 第三个就是扩展性。首先来看注释，它的扩展性就很差了，因为代码是读不到注释里面的值的，给它打分 70 分。注解它的扩展性就特别的强了，可以用 AOP 进行很多操作。

- 比如说第一个扩展，就是用 AOP 自动的去收集接口日志。

- 第二个很好用的扩展，就是用 AOP 将异常的接口进行告警，给它打分 95 分。

- 第四个效率。

- 第四个就是(开发)效率。对于注释来说自测是有点麻烦的，先要把它给导出来，比如导出的 Postman 里面，然后再进行自测。这个操作就是有点麻烦了，多了导出这一步，给它打分 75 分。注解这种方式自测是非常方便，应用启动之后就直接去访问就可以了。比如 Swagger 和 knife4j，knife4j 就像一个管理页面一样，特别的清爽，给它打分 95 分。

2. 现在算一下它们的总分，注释的得分就是 310 分，注解方式的得分是 355 分。注解方式要明显高于注释方式的。

3. 我在开发的时候就用的注解的方式，写了很多自定义的 AOP，用起来特别的方便。

下期视频再见，拜拜。