再見Swagger铁蹈!使用smart-doc無侵入生成接口文檔

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

smart-doc效果示例

html全局展示
請求參數(shù)示例
請求響應示例

開源地址:https://gitee.com/smart-doc-team/smart-doc

?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
  • 序言:七十年代末锻霎,一起剝皮案震驚了整個濱河市著角,隨后出現(xiàn)的幾起案子,更是在濱河造成了極大的恐慌旋恼,老刑警劉巖吏口,帶你破解...
    沈念sama閱讀 216,919評論 6 502
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件,死亡現(xiàn)場離奇詭異冰更,居然都是意外死亡产徊,警方通過查閱死者的電腦和手機,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 92,567評論 3 392
  • 文/潘曉璐 我一進店門蜀细,熙熙樓的掌柜王于貴愁眉苦臉地迎上來舟铜,“玉大人,你說我怎么就攤上這事奠衔∽慌伲” “怎么了?”我有些...
    開封第一講書人閱讀 163,316評論 0 353
  • 文/不壞的土叔 我叫張陵归斤,是天一觀的道長痊夭。 經(jīng)常有香客問我,道長脏里,這世上最難降的妖魔是什么她我? 我笑而不...
    開封第一講書人閱讀 58,294評論 1 292
  • 正文 為了忘掉前任,我火速辦了婚禮膝宁,結果婚禮上鸦难,老公的妹妹穿的比我還像新娘。我一直安慰自己员淫,他們只是感情好合蔽,可當我...
    茶點故事閱讀 67,318評論 6 390
  • 文/花漫 我一把揭開白布。 她就那樣靜靜地躺著介返,像睡著了一般拴事。 火紅的嫁衣襯著肌膚如雪。 梳的紋絲不亂的頭發(fā)上圣蝎,一...
    開封第一講書人閱讀 51,245評論 1 299
  • 那天刃宵,我揣著相機與錄音,去河邊找鬼徘公。 笑死牲证,一個胖子當著我的面吹牛,可吹牛的內容都是我干的关面。 我是一名探鬼主播坦袍,決...
    沈念sama閱讀 40,120評論 3 418
  • 文/蒼蘭香墨 我猛地睜開眼十厢,長吁一口氣:“原來是場噩夢啊……” “哼!你這毒婦竟也來了捂齐?” 一聲冷哼從身側響起蛮放,我...
    開封第一講書人閱讀 38,964評論 0 275
  • 序言:老撾萬榮一對情侶失蹤,失蹤者是張志新(化名)和其女友劉穎奠宜,沒想到半個月后包颁,有當?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體,經(jīng)...
    沈念sama閱讀 45,376評論 1 313
  • 正文 獨居荒郊野嶺守林人離奇死亡压真,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內容為張勛視角 年9月15日...
    茶點故事閱讀 37,592評論 2 333
  • 正文 我和宋清朗相戀三年娩嚼,在試婚紗的時候發(fā)現(xiàn)自己被綠了。 大學時的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片榴都。...
    茶點故事閱讀 39,764評論 1 348
  • 序言:一個原本活蹦亂跳的男人離奇死亡待锈,死狀恐怖,靈堂內的尸體忽然破棺而出嘴高,到底是詐尸還是另有隱情,我是刑警寧澤和屎,帶...
    沈念sama閱讀 35,460評論 5 344
  • 正文 年R本政府宣布拴驮,位于F島的核電站,受9級特大地震影響柴信,放射性物質發(fā)生泄漏套啤。R本人自食惡果不足惜,卻給世界環(huán)境...
    茶點故事閱讀 41,070評論 3 327
  • 文/蒙蒙 一随常、第九天 我趴在偏房一處隱蔽的房頂上張望潜沦。 院中可真熱鬧,春花似錦绪氛、人聲如沸唆鸡。這莊子的主人今日做“春日...
    開封第一講書人閱讀 31,697評論 0 22
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽争占。三九已至,卻和暖如春序目,著一層夾襖步出監(jiān)牢的瞬間臂痕,已是汗流浹背。 一陣腳步聲響...
    開封第一講書人閱讀 32,846評論 1 269
  • 我被黑心中介騙來泰國打工猿涨, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留握童,地道東北人。 一個月前我還...
    沈念sama閱讀 47,819評論 2 370
  • 正文 我出身青樓叛赚,卻偏偏與公主長得像澡绩,于是被迫代替她去往敵國和親稽揭。 傳聞我的和親對象是個殘疾皇子,可洞房花燭夜當晚...
    茶點故事閱讀 44,665評論 2 354

推薦閱讀更多精彩內容