smart-doc是什么宽闲?
smart-doc是一款同時支持JAVA REST API和Apache Dubbo RPC接口文檔生成的工具,零注解握牧、零學習成本、只需要寫標準JAVA注釋娩梨,smart-doc就能幫你生成一個簡易明了的Markdown沿腰、HTML5、Postman Collection2.0+狈定、OpenAPI 3.0+的文檔颂龙。
smart-doc怎么用?
1纽什、Add Maven Plugin
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.2.4.1</version>
<configuration>
<!--指定生成文檔的使用的配置文件,配置文件放在自己的項目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定項目名稱-->
<projectName>測試</projectName>
<!--smart-doc實現(xiàn)自動分析依賴樹加載第三方依賴的源碼措嵌,如果一些框架依賴庫加載不到導致報錯,這時請使用excludes排除掉-->
<excludes>
<!--格式為:groupId:artifactId;參考如下-->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
<!--自1.0.8版本開始芦缰,插件提供includes支持,配置了includes后插件會按照用戶配置加載而不是自動加載企巢,因此使用時需要注意-->
<!--smart-doc能自動分析依賴樹加載所有依賴源碼,原則上會影響文檔構建效率让蕾,因此你可以使用includes來讓插件加載你配置的組件-->
<includes>
<!--格式為:groupId:artifactId;參考如下-->
<!--也可以支持正則式如:com.alibaba:.* -->
<include>com.alibaba:fastjson</include>
</includes>
</configuration>
<executions>
<execution>
<goals>
<!--smart-doc提供了html浪规、openapi、markdown等goal探孝,可按需配置-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
2笋婿、在項目目錄下添加 smart-doc.json 配置文件,常用配置如下
{
"serverUrl": "http://localhost:8080", //服務器地址,非必須顿颅。導出postman建議設置成http://{{server}}方便直接在postman直接設置環(huán)境變量
"allInOne": true, //是否將文檔合并到一個文件中缸濒,一般推薦為true
"outPath": "src/main/resources/static/doc", //指定文檔的輸出路徑
"coverOld": true, //是否覆蓋舊的文件,主要用于mardown文件覆蓋
"createDebugPage": true,//@since 2.0.0 smart-doc支持創(chuàng)建可以測試的html頁面粱腻,僅在AllInOne模式中起作用庇配。
"projectName": "smart-doc",//配置自己的項目名稱
"sortByTitle":false,//接口標題排序,默認為false,@since 1.8.7版本開始
"showAuthor":true,//是否顯示接口作者名稱栖疑,默認是true,不想顯示可關閉
"allInOneDocFileName":"index.html"http://自定義設置輸出文檔名稱, @since 1.9.0
}
3讨永、在對應的接口、實體類中添加上標準JAVA注釋
/**
* 根據(jù)用戶id獲取用戶
* @param id
* @return
*/
@GetMapping("user/{id}")
public R<User> getUser(@PathVariable Integer id){
User user = new User();
user.setId(id);
user.setUsername("王大福");
return R.ok(user);
}
4遇革、利用maven插件卿闹,生成接口文檔
1.1 在idea中揭糕,可以直接通過maven helper中Plugins,smart-doc插件中生成對應的文檔
1.2 maven命令方式
//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc