wrdoclet（问道）使用手册

wrdoclet为远程服务接口文档而生。

传统的javadoc文档虽然较为清晰的表达了内部实现类的细节，但对于远程服务的接口使用方而言，往往无法快速从javadoc中找到需要使用的接口。并且很多内部实现类的细节对于接口调用方是不需要了解的。这些内容在doc文档中的展示反而会给需要调用接口的开发人员造成阅读干扰。因此，基于自定义doclet以及taglet，开发了wrdoclet。使得服务提供方可以自动生成接口文档。同时开发了一系列组件，可以与solr、jenkins集成。最终达到接口文档自动生成、发布的目的。

问道的特点：

• 代码无侵入。对接口文档的描述都融入在代码注释中。这种做法同时大大提高了代码的可阅读性
• 适用主流开发模式。 接口文档支持根据系统名以及代码分支进行展现，适用于微服务多分支并行开发
• 支持查询。服务端组件集成查询功能，可以快速定位接口。同时服务端作为接口文档的统一输出，提升了文档更新及通知的效率。
• 可自定义标签Tag。将接口根据Tag分组展示。方便阅读和查询
• 集成方便。一般的项目在POM中只需几行代码集成插件就可以生成简化的接口文档了

问道的推荐的开发模式： 在微服务开发过程中，很多情况需要服务方和调用方同时进行开发。服务方需要在服务代码还没有开发完成的时候就提供接口文档以便于调用方根据接口文档同时进行开发。这种情况问道推荐的开发模式是服务方编码人员先设计提交接口代码，不编写接口的实现逻辑。比如对于REST API，只定义对外服务的Controller及其action接口以及相关Request、Response的Bean即可。问道只需要这些代码就可以生成接口文档了。在利用持续集成工具将接口文档发布到服务端，调用方即可查阅接口文档并进行自己的逻辑编码。

本手册会详细说明注释规范，以及如何与maven集成。并且提供部署说明，介绍如何与solr、jenkins集成。为方便使用也可以使用提供的solr docker image进行集成。

点击链接加入群【问道】：https://jq.qq.com/?\_wv=1027&k=5N484nU