swaggerconfig詳解

一、swaggerconfig介紹

Swagger是一個集成了多種API文檔工具的框架，用於自動生成、描述、文檔化RESTful風格的Web服務。SwaggerConfig是Swagger的配置類，可以通過配置Swagger相關屬性來自定義Swagger的一些配置信息，如：接口文檔網址、當前系統的基本信息等等。

二、SwaggerConfig常用屬性

SwaggerConfig定義了很多屬性，這裡我們重點講解以下幾個常用的屬性。

1、apiInfo

apiInfo是Swagger文檔網站的基本信息設置，包括標題、描述、聯繫方式等信息。這些信息通常會包含在Swagger UI界面上。以下是一個apiInfo的示例：

@Bean
public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .apiInfo(new ApiInfoBuilder()
            .title("Petstore API")
            .description("API for petstore")
            .version("1.0.0")
            .build());
}

2、enable

enable屬性可用於控制Swagger是否啟用，通常情況下我們在測試環節中啟用Swagger，在生產環節中禁用Swagger。以下是一個enable的示例：

@Bean
public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .enable(true);
}

3、groupName

groupName屬性用於為生成的接口文檔指定分組名，方便文檔分類和管理。以下是一個groupName的示例：

@Bean
public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .groupName("pet");
}

4、securitySchemes

securitySchemes屬性用於為接口添加安全認證方式，可以選擇Basic認證、Token認證等安全方式。以下是一個securitySchemes的示例：

@Bean
public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .securitySchemes(Arrays.asList(apiKey()))
        .securityContexts(Arrays.asList(securityContext()));
}

private ApiKey apiKey() {
    return new ApiKey("mykey", "api_key", "header");
}

private SecurityContext securityContext() {
    return SecurityContext.builder()
        .securityReferences(defaultAuth())
        .forPaths(PathSelectors.regex("/anyPath.*"))
        .build();
}

List defaultAuth() {
    AuthorizationScope authorizationScope
        = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("mykey", authorizationScopes));
}

三、SwaggerConfig的其他屬性

除了上述常用屬性，SwaggerConfig還有很多其他的屬性可以使用。比如：useDefaultResponseMessages、ignoredParameterTypes、globalOperationParameters、directModelSubstitute、apiListingReferenceOrder、genericModelSubstitutes等等。

四、總結

通過配置SwaggerConfig，我們可以自定義Swagger的很多屬性，使接口文檔更加符合我們的需求。在編寫完API後，推薦使用Swagger框架來描述和測試你的API。Swagger可以讓每個團隊成員更好的了解API的定義，提高API的交互性，並糾正所有的誤差。