swagger作為一個被廣泛使用的在線接口文檔輔助工具，上手會用很容易，但想用好卻還是需要一定功夫的。所以呢，本篇文檔就和大家一起來聊一聊如何用好swagger，讓其真正的成為我們項目交付過程中的神兵利器。

更改接口文檔總標(biāo)題與描述

默認(rèn)的情況下，Swagger的界面整個文檔的名稱以及描述內(nèi)容都是通用值，這會讓人拿到文檔之后比較困惑，無法知曉這是哪個項目哪個系統(tǒng)哪個服務(wù)提供的接口，也不知道接口是哪個團(tuán)隊負(fù)責(zé)，哪位開發(fā)人員維護(hù)的。

比如下面這樣：

為了體現(xiàn)出接口文檔的專業(yè)性，讓人更容易知曉此接口文檔所屬系統(tǒng)、對應(yīng)版本、維護(hù)團(tuán)隊等信息，我們可以在代碼中根據(jù)需要自定義相關(guān)的內(nèi)容。

比如：

@Bean
public Docket createRestApi() {
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("資源管理系統(tǒng)接口文檔")
        .description("資源管理模塊對外供APP/WEB端調(diào)用的接口詳細(xì)文檔描述")
        .version("v1.0.0")
        .contact(new Contact("架構(gòu)悟道", "https://juejin.cn/user/1028798616709294","veezean@outlook.com"))
        .termsOfServiceUrl("https://juejin.cn/user/1028798616709294")
        .license("Apache License")
        .licenseUrl("http://xxx")
        .build();
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().build();
}

重新啟動并查看界面，可以發(fā)現(xiàn)界面上相關(guān)內(nèi)容已經(jīng)變更為我們自定義的內(nèi)容了，是不是比改動前顯得更加明晰與專業(yè)了？

上述swagger中支持自定義的描述性的字段信息，梳理如下：

按需顯示/隱藏相關(guān)接口內(nèi)容

手動編寫接口文檔的時候，我們可以根據(jù)實際情況靈活的去控制需要寫入到文檔中的接口內(nèi)容、以及接口的請求響應(yīng)體中的字段信息 —— 因為并不是系統(tǒng)中提供的所有的接口都需要體現(xiàn)在接口文檔中暴露給調(diào)用方去知曉的，比如有一些系統(tǒng)狀態(tài)監(jiān)控類的接口，只需要內(nèi)部使用即可。

對于Swagger而言，生成接口文檔的時候，默認(rèn)是掃描所有的@Controller中的全部接口方法全部顯示到文檔中，但其也貼心地考慮到了實際應(yīng)用中的這種按需隱藏或者展示接口內(nèi)容的訴求，并提供了多種不同的方式來支持。

下面一起來看下。

針對單個接口進(jìn)行隱藏

在單個接口方法的上方添加 @ApiOperation 注解說明，并指定 hidden = true即可將該接口從swagger界面能上隱藏：

@GetMapping("/test")
@ApiOperation(value = "內(nèi)部測試接口", hidden = true)
public String test() {
    return "OK";
}

啟動進(jìn)程，查看Swagger界面，發(fā)現(xiàn)該接口沒有出現(xiàn)在界面上：

隱藏整個Controller類中的接口

如果整個Controller類下面所有的接口都需要隱藏，則可以在Conntroller類上添加上@ApiIgnore注解可以了。

@RestController
@RequestMapping("/test")
@ApiIgnore
public class TestController {
// ... ignore ...
}

改動后重啟進(jìn)程，再打開swagger界面，發(fā)現(xiàn)TestController整個類的接口都沒有顯示。

這里補(bǔ)充一句，因為用于描述Controller類的接口含義的注解@Api中也有個hidden屬性，而且看其源碼注釋說明，如果設(shè)置hidden=true，應(yīng)該也是將該Controller類整體隱藏。但是實際上測試發(fā)現(xiàn)并沒有生效，這個實際使用的時候要小心這一點（基于swagger 2.7.0版本試驗，不確定是否為BUG）。

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {
    /**
     * Hides the operations under this resource.
     *
     * @return true if the api should be hidden from the swagger documentation
     */
    boolean hidden() default false;
}

僅顯示指定package路徑下的接口

我們的項目里面經(jīng)常會依賴或者引用一些三方j(luò)ar包，而這些三方j(luò)ar中有的時候也會提供一些接口，也會出現(xiàn)在我們的接口文檔中，這樣就會顯得接口文檔中存在很多不確定的內(nèi)容。

比如：

因為這部分邏輯并非業(yè)務(wù)代碼中提供的，所以我們沒法按照上面的方式，修改源碼添加hidden=true的方式來控制其不顯示。這個時候，就需要按照package進(jìn)行白名單控制的能力了。swagger還支持根據(jù)給定的basePackage以及paths進(jìn)行組合控制，僅顯示給定包下指定路徑下的接口。

@Bean
public Docket createRestApi() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("資源管理系統(tǒng)接口文檔")
            .description("資源管理模塊對外供APP/WEB端調(diào)用的接口詳細(xì)文檔描述")
            .version("v1.0.0")
            .build();
    ApiSelectorBuilder selectorBuilder = (new Docket(DocumentationType.SWAGGER_2)).apiInfo(apiInfo).select();
    selectorBuilder.apis(RequestHandlerSelectors.basePackage("com.jiagouwudao.resmanage"));
    selectorBuilder.paths(PathSelectors.any());
    return selectorBuilder.build();
}

這樣就可以保證出現(xiàn)在接口文檔里面的都是我們自己定義的接口了。重新啟動并刷新界面，會發(fā)現(xiàn)，只有指定package目錄下的Controller接口顯示在swagger界面上了。

隱藏響應(yīng)中不愿暴露的屬性

在項目開發(fā)過程中，如果我們的代碼沒有做強(qiáng)制的VO、DO隔斷，出于減少編碼量考慮，可能會使用同一個對象進(jìn)行內(nèi)部處理以及外部交互。比如：

定義一個OperateLog對象，為數(shù)據(jù)庫中T_OPERATE_LOG表所對應(yīng)的實體類，用于記錄每個用戶的操作行為；同時也作為recordOperateLog接口的請求Body體，用于傳遞需要記錄的用戶操作信息。

在上面的例子中：

• 作為數(shù)據(jù)表實體類進(jìn)行邏輯處理的時候，需要用到唯一主鍵id信息
• 作為recordOperateLog接口的請求Body體時，調(diào)用方是不需要指定這條記錄的ID值的（ID值會在存儲到DB的時候自動由DB生成唯一自增主鍵）

這種場景下，我們就希望提供出去的接口文檔中，在對recordOperateLog接口的請求body體中字段說明的時候，就不要體現(xiàn)出id字段，避免讓調(diào)用方產(chǎn)生疑惑，不知道id調(diào)用的時候應(yīng)該如何賦值。我們可以通過在指定字段上添加@ApiModelProperty注解并指定hidden = true來將其從接口文檔中隱藏掉。

比如：

@Data
@ApiModel("操作記錄信息")
public class OperateLog {
    @ApiModelProperty(value = "記錄唯一ID，無實際意義", hidden = true)
    private long id;
    @ApiModelProperty("操作類型，取值說明：1，新增；2，更新；3，刪除；4，查詢")
    private int operateType;
    @ApiModelProperty("操作用戶")
    private String user;
    @ApiModelProperty(value = "操作詳情")
    private String detail;
}

則界面中的接口文檔不會顯示id的有關(guān)信息（注意：僅接口文檔中不體現(xiàn)，不會影響具體請求或者響應(yīng)中此字段的實際值）。

關(guān)閉生產(chǎn)環(huán)境的swagger

考慮到生產(chǎn)環(huán)境的安全性，對于一些比較重要的系統(tǒng)，我們一般不太愿意將生產(chǎn)環(huán)境的接口文檔暴露出來，避免對系統(tǒng)的運(yùn)行埋下隱患。

在SpringBoot項目中，我們會為不同的環(huán)境提供不同的配置文件， 然后在啟動的時候使用 --spring.active.profile 來指定加載哪一份配置。

如果需要使Swagger可以被訪問，我們可以通過代碼中添加@EnableSwagger2注解的方式來實現(xiàn)。若限制僅在開發(fā)或測試環(huán)境上允許swagger訪問而生產(chǎn)環(huán)境不允許打開，則只需要讓這個添加了@EnableSwagger2注解的類根據(jù)當(dāng)前的運(yùn)行環(huán)境來決定是否加載就可以了。借助SpringBoot提供的@Profile注解，我們可以這樣來實現(xiàn)：

@Configuration
@EnableSwagger2
@Profile({"DEV", "TEST"})
public class SwaggerConfig {

}

這樣，就可以讓SwaggerConfig類在profile=PROD的時候不會被加載，也就不會開啟swagger的開關(guān)。使用 --spring.active.profile=PROD啟動進(jìn)程，嘗試訪問swagger界面，會發(fā)現(xiàn)無法打開：

給Swagger換個皮膚

默認(rèn)的swagger界面所有內(nèi)容都羅列居中顯示，然后需要一層層的展開去，操作上面不太方便，整體界面風(fēng)格也不太符合一個“文檔”的樣子。為了提升使用體驗，可以借助開源的knife4j框架來讓swagger變得更加好用。

使用方式很簡單，在已有的swagger依賴的基礎(chǔ)上，在pom.xml中新增如下引用依賴：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>2.0.4</version>
</dependency>

啟動進(jìn)程后，訪問 doc.html 頁面，比如 http://127.0.0.1:8088/doc.html，可以發(fā)現(xiàn)一個更加符合接口文檔體驗的新的界面：

當(dāng)然，這里我們使用了knife4j最簡單的一個“換膚”的特性，而作為一款優(yōu)秀的開源工具，knife4j所提供的能力遠(yuǎn)不止這些，有興趣的可以點擊此處詳細(xì)了解一下。

總結(jié)

好啦，關(guān)于如何補(bǔ)全Swagger接口的描述內(nèi)容、如何自主決定某些內(nèi)容的顯示與隱藏等相關(guān)的內(nèi)容，這里就給大家分享到這里啦。關(guān)于本篇內(nèi)容你有什么自己的想法或獨到見解么？