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

更改接口文檔總標題與描述

默認的情況下，Swagger的界面整個文檔的名稱以及描述內容都是通用值，這會讓人拿到文檔之后比較困惑，無法知曉這是哪個項目哪個系統哪個服務提供的接口，也不知道接口是哪個團隊負責，哪位開發人員維護的。

比如下面這樣：

為了體現出接口文檔的專業性，讓人更容易知曉此接口文檔所屬系統、對應版本、維護團隊等信息，我們可以在代碼中根據需要自定義相關的內容。

比如：

@Bean
public Docket createRestApi() {
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("資源管理系統接口文檔")
        .description("資源管理模塊對外供APP/WEB端調用的接口詳細文檔描述")
        .version("v1.0.0")
        .contact(new Contact("架構悟道", "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();
}

重新啟動并查看界面，可以發現界面上相關內容已經變更為我們自定義的內容了，是不是比改動前顯得更加明晰與專業了？

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

按需顯示/隱藏相關接口內容

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

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

下面一起來看下。

針對單個接口進行隱藏

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

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

啟動進程，查看Swagger界面，發現該接口沒有出現在界面上：

隱藏整個Controller類中的接口

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

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

改動后重啟進程，再打開swagger界面，發現TestController整個類的接口都沒有顯示。

這里補充一句，因為用于描述Controller類的接口含義的注解@Api中也有個hidden屬性，而且看其源碼注釋說明，如果設置hidden=true，應該也是將該Controller類整體隱藏。但是實際上測試發現并沒有生效，這個實際使用的時候要小心這一點（基于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路徑下的接口

我們的項目里面經常會依賴或者引用一些三方jar包，而這些三方jar中有的時候也會提供一些接口，也會出現在我們的接口文檔中，這樣就會顯得接口文檔中存在很多不確定的內容。

比如：

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

@Bean
public Docket createRestApi() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("資源管理系統接口文檔")
            .description("資源管理模塊對外供APP/WEB端調用的接口詳細文檔描述")
            .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();
}

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

隱藏響應中不愿暴露的屬性

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

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

在上面的例子中：

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

這種場景下，我們就希望提供出去的接口文檔中，在對recordOperateLog接口的請求body體中字段說明的時候，就不要體現出id字段，避免讓調用方產生疑惑，不知道id調用的時候應該如何賦值。我們可以通過在指定字段上添加@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的有關信息（注意：僅接口文檔中不體現，不會影響具體請求或者響應中此字段的實際值）。

關閉生產環境的swagger

考慮到生產環境的安全性，對于一些比較重要的系統，我們一般不太愿意將生產環境的接口文檔暴露出來，避免對系統的運行埋下隱患。

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

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

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

}

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

給Swagger換個皮膚

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

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

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

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

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

總結

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