Java Swagger UI如何自定义接口文档样式或添加授权功能？

Question

在使用Java集成Swagger UI时，如何自定义接口文档的样式或添加授权功能是一个常见的技术问题。默认情况下，Swagger UI提供基础的展示样式，但项目需求可能需要调整字体、颜色或布局等。通过修改`swagger-ui.html`文件或引入自定义CSS文件，可以实现样式覆盖。例如，在Spring Boot项目中，创建一个`/src/main/resources/static/swagger-ui.css`文件，并在其中定义样式规则，然后在`swagger-ui.html`中引用该CSS文件即可。 对于授权功能，可通过配置`SwaggerConfig`类中的`securitySchemes`和`securityContexts`来实现。例如，添加OAuth2或API Key认证，允许用户在Swagger界面输入令牌后测试受保护的接口。这种配置不仅提升了文档的专业性，还增强了接口测试的便利性。如何正确配置这些功能以满足特定需求，是开发者需要重点关注的问题。

Answer 1

1. 了解Swagger UI默认样式及其局限性

在Java项目中集成Swagger UI时，默认的接口文档样式虽然功能齐全，但可能无法满足特定项目的个性化需求。例如，字体、颜色和布局等元素可能需要根据品牌风格进行调整。

以下是常见的技术问题：

• 如何覆盖默认的样式规则？
• 如何通过自定义CSS实现更专业的外观？

在Spring Boot项目中，可以通过创建一个自定义CSS文件来实现样式覆盖。例如，在/src/main/resources/static/目录下创建一个名为swagger-ui.css的文件，并添加以下规则：

body {
    font-family: 'Arial', sans-serif;
    background-color: #f9f9f9;
}
.swagger-ui .opblock-summary-method {
    color: #007bff;
}
    

2. 自定义Swagger UI样式的方法

为了实现样式覆盖，开发者可以按照以下步骤操作：

1. 创建自定义CSS文件并定义样式规则。
2. 在swagger-ui.html文件中引用该CSS文件。

以下是一个示例swagger-ui.html文件的部分代码：

<link rel="stylesheet" type="text/css" href="swagger-ui.css">
    

此外，还可以通过修改index.html中的swagger-initializer.js配置，进一步调整UI行为。

3. 配置授权功能以增强接口测试便利性

除了样式自定义，Swagger UI还支持多种授权机制，如OAuth2和API Key认证。这些功能可以通过配置SwaggerConfig类中的securitySchemes和securityContexts来实现。

以下是一个示例配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(List.of(apiKey()))
                .securityContexts(List.of(securityContext()));
    }

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

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build();
    }

    List defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        return List.of(new SecurityReference("Authorization", new AuthorizationScope[]{authorizationScope}));
    }
}
    

通过上述配置，用户可以在Swagger界面输入令牌后测试受保护的接口。

4. 技术实现流程分析

为了更好地理解整个过程，以下是一个简单的流程图：

graph TD;
            A[开始] --> B{选择功能};
            B -->|样式自定义| C[创建自定义CSS];
            B -->|授权配置| D[配置SwaggerConfig];
            C --> E[引用CSS文件];
            D --> F[测试接口];

从流程图可以看出，无论是样式自定义还是授权配置，都需要明确目标并逐步实施。