哈嘍，大家好，我是了不起。

首先，Swagger 這個(gè)工具能夠自動(dòng)生成 API 接口文檔，在線調(diào)試，節(jié)省了很多書寫文檔的時(shí)間，非常強(qiáng)大。

但是，想要文檔生成的合格，還是要書寫大量的注解。有沒有一種連注解都不用寫的方式呢？

smart-doc簡(jiǎn)介

今天了不起給大家推薦一個(gè)技術(shù)：smart-doc，看名字就知道，它是 智能-文檔。直接分析代碼，根據(jù)代碼含義生成文檔（開個(gè)玩笑，它還沒有那么智能）；其實(shí)它是利用的注釋，來(lái)生成文檔，還是需要寫注釋的。

官方介紹：smart-doc是一款同時(shí)支持JAVA REST API和Apache Dubbo RPC接口文檔生成的工具，smart-doc在業(yè)內(nèi)率先提出基于JAVA泛型定義推導(dǎo)的理念， 完全基于接口源碼來(lái)分析生成接口文檔，不采用任何注解侵入到業(yè)務(wù)代碼中。你只需要按照java-doc標(biāo)準(zhǔn)編寫注釋， smart-doc就能幫你生成一個(gè)簡(jiǎn)易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文檔。

swagger和smart-doc的對(duì)比

我們來(lái)看看swagger和smart-doc的區(qū)別

來(lái)看看smart-doc 的代碼

如果是swagger 的寫法，每個(gè)字段都要加上 @ApiModelProperty("xxx") 的注解，如果有幾十個(gè)字段，幾十個(gè)類，那代碼量多的可不小。

不過這些類一般都是自動(dòng)生成工具生成的，對(duì)寫代碼的人影響不大，不過這樣子寫倒是簡(jiǎn)潔了不少，甚得我意~

可能有人就說(shuō)了，我不寫注釋，只寫swagger注解，看起來(lái)也很簡(jiǎn)潔，這也確實(shí)沒錯(cuò)。

確實(shí)看起來(lái)很簡(jiǎn)潔，不過沒有文檔注釋的情況下，在其他類里你是看不到這個(gè)字段的解釋的，每次找字段都得回到這個(gè)類看看到底是不是這個(gè)字段。如果你和同事們的英語(yǔ)都 very good，當(dāng)我沒說(shuō)。

如果是api接口，smart-doc想要生成文檔，需要寫成這樣（好像看起來(lái)什么都沒寫）

而swagger就需要加上@ApiOperation()這個(gè)注解，如果是個(gè)參數(shù)多的接口，還需要@ApiImplicitParams()這個(gè)注解，徒增學(xué)習(xí)成本

使用smart-doc

總共需要3步：

1.引入pom依賴，是一個(gè)插件

<!-- smart-doc插件 -->
<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>${smart-doc-plugin.version}</version>
    <configuration>
        <!--指定生成文檔的使用的配置文件-->
        <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
        <!--指定項(xiàng)目名稱-->
        <projectName>${project.name}</projectName>
        <excludes>
            <!--格式為：groupId:artifactId;參考如下-->
            <!--也可以支持正則式如：com.alibaba:.* -->
            <exclude>com.fu:common-.*</exclude>
            <exclude>com.fu:generator</exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在執(zhí)行編譯時(shí)啟動(dòng)smart-doc，則將phase注釋掉-->
            <phase>compile</phase>
            <goals>
                <goal>openapi</goal>
            </goals>
        </execution>
    </executions>
</plugin>

2.編寫smart-doc.json文件

{
  // 參考文檔：https://smart-doc-group.github.io/#/zh-cn/start/quickstart
  "outPath": "D:\\111",

  "coverOld": true,
  "allInOne": true, // 是否將文檔合并到一個(gè)文件中，一般推薦為true
  "createDebugPage": true,//@since 2.0.0 smart-doc支持創(chuàng)建可以測(cè)試的html頁(yè)面，僅在AllInOne模式中起作用。
  "isStrict": false, //是否開啟嚴(yán)格模式
  // controller包過濾，多個(gè)包用英文逗號(hào)隔開
  "packageFilters": "com.fu.system.controller.*",
  "projectName": "system",
  "sortByTitle": true, // 接口排序
  "ignoreRequestParams":[ //忽略請(qǐng)求參數(shù)對(duì)象，把不想生成文檔的參數(shù)對(duì)象屏蔽掉，@since 1.9.2
    "javax.servlet.http.HttpServletRequest",
    "javax.servlet.http.HttpServletResponse",
    "javax.servlet.http.HttpSession"
   ]
}

3.運(yùn)行這個(gè)插件，如果很熟悉mvn命令，在命令行運(yùn)行它也行；可以生成openapi、postman、html、Markdown等各種格式的文檔

https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc

文檔自動(dòng)化

如果它不能和swagger一樣，自動(dòng)部署文檔，還得手動(dòng)，那也不會(huì)來(lái)推薦這個(gè)了。

官方推薦方式：smart-doc + Torna 

需要額外部署一個(gè) Torna 文檔接口服務(wù)，類似 yapi；很多企業(yè)也都是單獨(dú)部署的接口文檔服務(wù)。

可以看出來(lái)界面比swagger好太多了

了不起這里給大家另一種方案，本地自動(dòng)部署，smart-doc + apifox（postman應(yīng)該也可以）

apifox -> 接口導(dǎo)入 -> 自動(dòng)同步

這個(gè)數(shù)據(jù)源URL可以直接配置為 file:///D:/111/openapi.json，在你配置pom的時(shí)候，直接配置成編譯項(xiàng)目時(shí)生成 openapi格式的文檔，就可以自動(dòng)部署到apifox，完美~

小結(jié)

今天了不起對(duì)這個(gè)smart-doc就介紹到這里了，感興趣的小伙伴可以用起來(lái)了，對(duì)代碼0侵入，簡(jiǎn)直太適合我這種強(qiáng)迫癥患者了。