還在用Swagger？試試這款零註解侵入的API文件生成工具，跟Postman絕配！

前後端介面聯調需要API文件，我們經常會使用工具來生成。之前經常使用Swagger來生成，最近發現一款好用的API文件生成工具smart-doc, 它有著很多Swagger不具備的特點，推薦給大家。

SpringBoot實戰電商專案mall（50k+star）地址：https://github.com/macrozheng/mall

聊聊Swagger

在我們使用Swagger的時候，經常會需要用到它的註解，比如@Api、@ApiOperation這些，Swagger通過它們來生成API文件。比如下面的程式碼：

Swagger對程式碼的入侵性比較強，有時候程式碼註釋和註解中的內容有點重複了。有沒有什麼工具能實現零註解入侵，直接根據程式碼註釋生成API文件呢？smart-doc恰好是這種工具！

smart-doc簡介

smart-doc是一款API文件生成工具，無需多餘操作，只要你規範地寫好程式碼註釋，就能生成API文件。同時能直接生成Postman除錯檔案，一鍵匯入Postman即可除錯，非常好用！

smart-doc具有如下優點：

生成API文件

接下來我們把smart-doc整合到SpringBoot專案中，體驗一下它的API文件生成功能。

首先我們需要在專案中新增smart-doc的Maven外掛，可以發現smart-doc就是個外掛，連依賴都不用新增，真正零入侵啊；

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.2.8</version>
    <configuration>
        <!--指定smart-doc使用的配置檔案路徑-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定專案名稱-->
        <projectName>mall-tiny-smart-doc</projectName>
    </configuration>
</plugin>

接下來在專案的resources目錄下，新增配置檔案smart-doc.json，屬性說明直接參考註釋即可；

{
  "serverUrl": "http://localhost:8088", //指定後端服務訪問地址
  "outPath": "src/main/resources/static/doc", //指定文件的輸出路徑，生成到專案靜態檔案目錄下，隨專案啟動可以檢視
  "isStrict": false, //是否開啟嚴格模式
  "allInOne": true, //是否將文件合併到一個檔案中
  "createDebugPage": false, //是否建立可以測試的html頁面
  "packageFilters": "com.macro.mall.tiny.controller.*", //controller包過濾
  "style":"xt256", //基於highlight.js的程式碼高設定
  "projectName": "mall-tiny-smart-doc", //配置自己的專案名稱
  "showAuthor":false, //是否顯示介面作者名稱
  "allInOneDocFileName":"index.html" //自定義設定輸出文件名稱
}

開啟IDEA的Maven皮膚，雙擊smart-doc外掛的smart-doc:html按鈕，即可生成API文件；

此時我們可以發現，在專案的static/doc目錄下已經生成如下檔案；

執行專案，訪問生成的API介面文件，發現文件非常詳細，包括了請求引數和響應結果的各種說明，訪問地址：http://localhost:8088/doc/ind...

我們回過來看下實體類的程式碼，可以發現我們只是規範地新增了欄位註釋，生成文件的時候就自動有了；

public class PmsBrand implements Serializable {
    /**
     * ID
     */
    private Long id;

    /**
     * 名稱
     * @required
     */
    private String name;

    /**
     * 首字母
     * @since 1.0
     */
    private String firstLetter;

    /**
     * 排序
     */
    private Integer sort;

    /**
     * 是否為品牌製造商(0,1)
     */
    private Integer factoryStatus;

    /**
     * 顯示狀態(0,1)
     * @ignore
     */
    private Integer showStatus;

    /**
     * 產品數量
     */
    private Integer productCount;

    /**
     * 產品評論數量
     */
    private Integer productCommentCount;

    /**
     * 品牌logo
     */
    private String logo;

    /**
     * 專區大圖
     */
    private String bigPic;

    /**
     * 品牌故事
     */
    private String brandStory;
    //省略getter、setter方法
}

再來看下Controller中程式碼，我們同樣規範地在方法上新增了註釋，生成API文件的時候也自動有了；

/**
 * 商品品牌管理
 */
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;
    
    /**
     * 分頁查詢品牌列表
     *
     * @param pageNum 頁碼
     * @param pageSize 分頁大小
     */
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    @ResponseBody
    @PreAuthorize("hasRole('ADMIN')")
    public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
                                                                Integer pageNum,
                                                        @RequestParam(value = "pageSize", defaultValue = "3")
                                                                Integer pageSize) {
        List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
        return CommonResult.success(CommonPage.restPage(brandList));
    }
}

當然smart-doc還提供了自定義註釋tag，用於增強文件功能；
- @ignore：生成文件時是否要過濾該屬性；
- @required：用於修飾介面請求引數是否必須；
- @since：用於修飾介面中屬性新增的版本號。
為了寫出優雅的API文件介面，我們經常會對返回結果進行統一封裝，smart-doc也支援這樣的設定，在smart-doc.json中新增如下配置即可；

{
  "responseBodyAdvice":{ //統一返回結果設定
    "className":"com.macro.mall.tiny.common.api.CommonResult" //對應封裝類
  }
}

我們也經常會用列舉型別來封裝狀態碼，在smart-doc.json中新增如下配置即可；

{
  "errorCodeDictionaries": [{ //錯誤碼列表設定
    "title": "title",
    "enumClassName": "com.macro.mall.tiny.common.api.ResultCode", //錯誤碼列舉類
    "codeField": "code", //錯誤碼對應欄位
    "descField": "message" //錯誤碼描述對應欄位
  }]
}

配置成功後，即可在API文件中生成錯誤碼列表；

有時候我們也會想給某些介面新增自定義請求頭，比如給一些需要登入的介面新增Authorization頭，在smart-doc.json中新增如下配置即可；

{
  "requestHeaders": [{ //請求頭設定
    "name": "Authorization", //請求頭名稱
    "type": "string", //請求頭型別
    "desc": "token請求頭的值", //請求頭描述
    "value":"token請求頭的值", //請求頭的值
    "required": false, //是否必須
    "since": "-", //新增版本
    "pathPatterns": "/brand/**", //哪些路徑需要新增請求頭
    "excludePathPatterns":"/admin/login" //哪些路徑不需要新增請求頭
  }]
}