最近调研了接口文档生成工具，发现了 smart-doc，但是不支持公司内部的微服务，于是在 issue 上相同问题的内容下提问了下

https://github.com/TongchengOpenSource/smart-doc/issues/683

没想到社区很快回复了，并列出了可行思路。

https://github.com/TongchengOpenSource/smart-doc/discussions/795

我看了下思路，又看了下代码，发现实现起来比想象的要简单很多。

于是捣鼓了半天，提交了代码

https://github.com/TongchengOpenSource/smart-doc/pull/797 https://github.com/TongchengOpenSource/smart-doc-maven-plugin/pull/70 https://github.com/smart-doc-group/smart-doc-group.github.io/pull/87

很快经过 review 修改后合并了。

哈哈，开心。

以后只要增加 @javadoc 注释，就可以支持普通 service 接口了。

背景

由于后端接口众多，接口文档的维护不好，因此需要调研相关接口管理工具，来规范化接口文档，提高开发和沟通效率。

工具

Swagger

介绍

• swagger 通过代码注解将相关注释内容通过 swagger-ui 体现到接口文档上，文档会随着项目启动而实时变化。
• 国内目前多数使用的为 springfox-swagger2（最近版本停留在 2020-07 月 https://github.com/springfox/springfox）
• 最新的版本已经改为 springdoc（https://github.com/springdoc/springdoc-openapi）

使用

由于国内主要使用的 springfox-swagger2， 所以这里就主要介绍下 swagger2 注解的使用。

https://juejin.cn/post/6993166706398986277

Smart-doc

介绍

• Smart-doc 是基于java 标准注释来生成对应的文档接口
• 运行时代码无 smart-doc 相关内容，需要利用 mvn 插件生成对应接口文档
• 文档不会在项目启动时实时更新，但是可以在编译期更新
• Github: https://github.com/TongchengOpenSource/smart-doc

使用

https://smart-doc-group.github.io/#/zh-cn/start/guide

集成

https://smart-doc-group.github.io/#/zh-cn/start/quickstart

优劣势分析

Swagger: 优点：使用广泛，代码中已经集成，方便前端调试 缺点：需要侵入代码，通过运行时反射机制实现，代码库不会更新

初探

MongoDB 感觉上存的主要是对象，也可以理解为文档信息