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的交互性，并纠正所有的误差。