Apiggs —— 非侵入性的 RestDoc 文件生成工具

摘要： 程式員一直以來都有一個煩惱，只想寫程式碼，不想寫文件。程式碼就表達了我的思想和靈魂。 Python提出了一個方案，叫docstring，來試圖解決這個問題。即編寫程式碼，同時也能寫出文件，保持程式碼和文件的一致。docstring說白了就是一堆程式碼中的註釋。Python的docstring可...

程式員一直以來都有一個煩惱，只想寫程式碼，不想寫文件。程式碼就表達了我的思想和靈魂。 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檔案，原始檔渲染結果，效果如下圖

本文來自雲棲社群合作伙伴“開源中國”

本文作者：王練

ofollow,noindex">原文連結