?Apiggs非侵入的 RestDoc 文檔生成工具

前言

程序員一直以來(lái)都有一個(gè)煩惱，只想寫代碼，不想寫文檔。代碼就表達(dá)了我的思想和靈魂。 Python提出了一個(gè)方案，叫docstring，來(lái)試圖解決這個(gè)問(wèn)題。即編寫代碼，同時(shí)也能寫出文檔，保持代碼和文檔的一致。docstring說(shuō)白了就是一堆代碼中的注釋。Python的docstring可以通過(guò)help函數(shù)直接輸出一份有格式的文檔，本工具的思想與此類似。

代碼即文檔

Apiggs是一個(gè)非侵入的RestDoc文檔生成工具。工具通過(guò)分析代碼和注釋，獲取文檔信息，生成RestDoc文檔。

有這樣一段代碼

/**
 * Building a RESTful Web Service
 * 來(lái)自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));
    }
}

運(yùn)行插件

gradle  運(yùn)行  task: Tasks/documentation/apiggs

maven 運(yùn)行  compile

生成文檔

在編譯目錄下生成apiggs文件夾，并生成三個(gè)文件：

1. .json文件，可直接導(dǎo)入postman

1. .adoc文件，Asciidoc源文件

1. .html文件，源文件渲染結(jié)果，效果如下圖

查看更多信息：Wiki