程序员一直以来都有一个烦恼,只想写代码,不想写文档。代码就表达了我的思想和灵魂。 Python提出了一个方案,叫docstring,来试图解决这个问题。即编写代码,同时也能写出文档,保持代码和文档的一致。docstring说白了就是一堆代码中的注释。Python的docstring可以通过help函数直接输出一份有格式的文档,本工具的思想与此类似。
Apiggs是一个 非侵入 的RestDoc文档生成工具。工具通过分析代码和注释,获取文档信息,生成RestDoc文档。
/** * Building a RESTful Web Service * 来自spring的官方示例:https://spring.io/guides/gs/rest-service/ */ @RestController public class GreetingController { private static final String template = "Hello, %s!"; private final AtomicLong counter = new AtomicLong(); /** * Web Endpoint greeting * @param name who is this * @return */ @RequestMapping("/greeting") public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) { return new Greeting(counter.incrementAndGet(), String.format(template, name)); } }
gradle 运行 task: Tasks/documentation/apiggs
maven 运行 compile
在编译目录下生成apiggs文件夹,并生成三个文件:
1. .json文件,可直接导入postman
1. .adoc文件,Asciidoc源文件
1. .html文件,源文件渲染结果,效果如下图
查看更多信息:Wiki