JAVA中讓Swagger產出更加符合我們訴求的描述檔案，按需決定顯示或者隱藏指定內容

大家好，又見面啦，

在前一篇檔案《JAVA中自定義擴展Swagger的能力，自動生成引數取值含義說明，提升開發效率》中，我們探討了如何通過自定義注解的方式擴展swagger的能力讓Swagger支持自動從指定的列舉類生成介面檔案中的欄位描述的實作思路，

其實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","[email protected]"))
        .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 = "https://www.cnblogs.com/softwarearch/archive/2022/09/08/內部測驗介面", 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 = "https://www.cnblogs.com/softwarearch/archive/2022/09/08/記錄唯一ID，無實際意義", hidden = true)
    private long id;
    @ApiModelProperty("操作型別，取值說明： 1，新增；2，更新；3，洗掉；4，查詢")
    private int operateType;
    @ApiModelProperty("操作用戶")
    private String user;
    @ApiModelProperty(value = "https://www.cnblogs.com/softwarearch/archive/2022/09/08/操作詳情")
    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介面的描述內容、如何自主決定某些內容的顯示與隱藏等相關的內容，這里就給大家分享到這里啦，關于本篇內容你有什么自己的想法或獨到見解么？歡迎在評論區一起交流探討下吧，

????另外：

• 關于本文中涉及的演示代碼的完整示例，我已經整理并提交到github中，如果您有需要，可以自取：https://github.com/veezean/JavaBasicSkills

我是悟道，聊技術、又不僅僅聊技術~

如果覺得有用，請點贊 + 關注讓我感受到您的支持，也可以關注下我的公眾號【架構悟道】，獲取更及時的更新，

期待與你一起探討，一起成長為更好的自己，

本文來自博客園，作者：架構悟道，歡迎關注公眾號[架構悟道]持續獲取更多干貨，轉載請注明原文鏈接：https://www.cnblogs.com/softwarearch/p/16668359.html

標籤：其他

上一篇：一，Spring的簡介和安裝，深入理解IOC容器及測驗

下一篇：并發編程AQS原始碼分析