如何优雅的生成接口文档？

我们知道在项目开发阶段，接口文档基本上是必备产物了，一般由后端开发人员提供，作为和前端人员进行前后端接口联调的桥梁，或者与别的项目模块进行交互提供指导等等，接口文档的准确性，实时性，详细与否等，都会极大的影响前面的操作。那么如何才能优雅的生成接口文档呢？

其实对于做开发的大多数人来说，多多少少都听过swagger，它是一个较为流行的接口文档管理工具，使用起来非常方便。所以大多数人都会使用swagger来生成接口文档，但是今天我要介绍另外一种生成接口文档的方式。通过swagger插件(如jar包)解析编写了接口注解的java代码, 而后通过生成的swagger.json文件解析出接口信息并导入接口文档管理工具yapi（yapi是去哪儿的大前端团队开发，基于react+antd的一套接口文档管理工具）。具体操作步骤如下：

编写注解

图中的@POST, @ApiResponses, @Path等意思都很明显，因为我的java只有一点点语法基础, 所以理解可能有点出入, 我这里简单理解为注释的意思。如有不对求指教。

这个类里面, 有user和login属性, 分别给属性加了类似这样的注解

通过注解生成swagger.json解决好pom文件的依赖后。在项目目录执行:mvn clean compile

导入yapiyapi是去哪儿的大前端团队开发，基于react+antd的一套接口文档管理工具，可以自己下载体验下，真心不错。至于不需要yapi, 钟爱原生swagger的童鞋, 也可以直接将swagger.json放入你的本地swaggerUI中查看接口文档。

当然这种方法有个缺点就是开发需要在每个model的类加上注解, 写每一个接口也需要注解，这里只是提供另外一种生成接口的思路。

如果觉得笨猫的回答对你有用，点个关注谢谢。