OpenAPI Nâng Cao: Security, Grouping và Triết Lý API-First

TL;DR: Để đưa tài liệu API vào môi trường thực tế an toàn, bài học này giải quyết 4 bài toán kỹ thuật nâng cao: (1) Khai báo @SecurityScheme cho JWT Bearer giúp Swagger UI tích hợp nút "Authorize", tự động gắn token vào header cho mọi lượt thử nghiệm; (2) Sử dụng GroupedOpenApi để chia nhỏ tài liệu thành các nhóm độc lập (Public, Admin, Internal); (3) Loại bỏ các endpoint bảo trì và debug qua @Hidden hoặc cấu hình exclude; (4) Xây dựng chiến lược phân tách tài liệu production để tránh rò rỉ diện mạo tấn công (attack surface). Cuối cùng, phân tích sự đánh đổi giữa hai triết lý phát triển API-First và Code-First theo quy mô đội ngũ.

1. Cấu hình Security Scheme JWT thế nào để Swagger UI có nút Authorize?

Khi các API yêu cầu xác thực JWT, lập trình viên cần cơ chế gửi kèm token khi bấm "Try it out" trên giao diện Swagger UI:

@Configuration
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    in = SecuritySchemeIn.HEADER,
    description = "Dien JWT token nhan duoc tu endpoint /api/auth/login"
)
public class OpenApiSecurityConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("TaskFlow API").version("v1.0.0"))
            // Ap dung yeu cau token cho tat ca endpoint mac dinh
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
    }
}

Đối với các endpoint không yêu cầu xác thực (như đăng nhập, đăng ký), sử dụng @SecurityRequirements rỗng để ghi đè:

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @SecurityRequirements // Override global: khong hien thi o khoa va khong yeu cau token
    @PostMapping("/login")
    public TokenResponse login(@Valid @RequestBody LoginRequest req) {
        return authService.login(req);
    }
}

Trên Swagger UI, lập trình viên bấm vào nút Authorize, dán JWT token một lần duy nhất. Kể từ đó, toàn bộ request gửi qua "Try it out" sẽ tự động được đính kèm header Authorization: Bearer <token>.

2. GroupedOpenApi giúp chia nhỏ tài liệu API theo nhóm người dùng ra sao?

Khi hệ thống có hàng trăm endpoint bao gồm API người dùng, API quản trị và API giao tiếp nội bộ, việc gộp chung vào một tài liệu duy nhất gây rối loạn và tiềm ẩn rủi ro lộ cấu trúc quản trị.

GroupedOpenApi cho phép chia nhỏ tài liệu thành các đặc tả riêng biệt:

@Configuration
public class OpenApiGroupConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public-v1")
            .displayName("1. Public API v1")
            .pathsToMatch("/api/v1/**")
            .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
            .group("admin")
            .displayName("2. Admin API")
            .pathsToMatch("/api/admin/**")
            .addOpenApiCustomizer(openApi ->
                openApi.info(new Info().title("TaskFlow Admin Management").version("v1")))
            .build();
    }
}

Mỗi nhóm sẽ có đường dẫn tải tài liệu JSON riêng biệt:

• Nhóm Public: /v3/api-docs/public-v1
• Nhóm Admin: /v3/api-docs/admin

Trên giao diện Swagger UI, người dùng có thể chuyển đổi linh hoạt thông qua menu thả xuống "Select Definition" ở góc trên bên phải.

3. Làm thế nào để ẩn các endpoint nội bộ nhạy cảm khỏi tài liệu?

Sử dụng annotation @Hidden

Đặt @Hidden trên method hoặc controller class để chỉ thị cho springdoc bỏ qua khi sinh tài liệu:

@Hidden // Khong xuat hien trong OpenAPI spec
@GetMapping("/internal/metrics/memory")
public Map<String, Object> getMemoryMetrics() {
    return systemService.getMemoryStats();
}

Ẩn hàng loạt qua cấu hình application.yml

springdoc:
  paths-to-exclude: /internal/**, /debug/**, /actuator/**
  packages-to-exclude: com.olhub.taskflow.internal
  show-actuator: false

4. Nên tắt hay bảo vệ Swagger UI trên môi trường Production?

Để Swagger UI mở công khai trên môi trường Production mang lại nhiều rủi ro bảo mật:

• Lộ diện mạo tấn công (Attack Surface): Kẻ tấn công nắm rõ toàn bộ danh sách endpoint, các tham số bắt buộc và cấu trúc dữ liệu nội bộ.
• Lộ quy tắc kiểm thực: Schema tài liệu để lộ regex, độ dài tối thiểu của mật khẩu, giúp tin tặc xây dựng kịch bản brute-force chính xác hơn.
• Công cụ dò quét miễn phí: Tính năng "Try it out" vô tình biến thành giao diện tiện lợi cho kẻ xấu thực hiện tấn công dò lỗi.

Các chiến lược triển khai Production:

1. Vô hiệu hóa hoàn toàn trên Production (Khuyến nghị):
   YAML

   Sao chép

   # application-prod.yml
   springdoc:
     api-docs:
       enabled: false
     swagger-ui:
       enabled: false
   

2. Bảo vệ bằng Spring Security (Dành cho nội bộ công ty): Yêu cầu tài khoản có quyền ROLE_DEVELOPER mới được phép truy cập vào /swagger-ui.html và /v3/api-docs/**.

5. So sánh mô hình API-First và Code-First theo quy mô dự án ra sao?

Bảng đối chiếu hai triết lý phát triển:

6. Những cạm bẫy bảo mật thường gặp với tài liệu OpenAPI là gì?

1. Quên miễn trừ các endpoint Public: Khai báo Security Scheme toàn cục mà quên gắn @SecurityRequirements trên /api/auth/login khiến người dùng không thể thử nghiệm đăng nhập trên UI.
2. Khai báo GroupedOpenApi rỗng: Khởi tạo GroupedOpenApi nhưng quên gọi pathsToMatch(), dẫn đến việc cả nhóm con vẫn nạp toàn bộ 100% endpoint của hệ thống.
3. Phụ thuộc vào bảo mật bằng cách che giấu (Security through Obscurity): Đổi đường dẫn /swagger-ui.html thành chuỗi ngẫu nhiên mà không bật xác thực; các công cụ quét tự động vẫn có thể dò ra dễ dàng.

7. OpenAPI nâng cao kết nối với các thành phần khác ra sao?

• OpenAPI & springdoc Cơ Bản: Cung cấp các thao tác scan và sinh tài liệu nền tảng.
• Mini-challenge TaskFlow v1: Thử thách tổng hợp áp dụng toàn diện JWT Security Scheme, Grouping và Validation trong ứng dụng thực tế.

8. Những điểm then chốt cần ghi nhớ là gì?

• Khai báo @SecurityScheme và gắn @SecurityRequirement để kích hoạt nút Authorize hỗ trợ JWT trong Swagger UI.
• Sử dụng GroupedOpenApi để phân tách tài liệu API rõ ràng theo vai trò người dùng (Public vs Admin).
• @Hidden chỉ ẩn khỏi tài liệu, không có tác dụng bảo vệ an ninh tầng mạng.
• Vô hiệu hóa hoặc đặt mật khẩu bảo vệ Swagger UI trên môi trường Production.
• Cân nhắc lựa chọn giữa Code-First và API-First tùy thuộc vào quy mô nhân sự và mức độ song song hóa công việc.

9. Bài tập tự kiểm tra mức độ hiểu sâu

Bài tiếp theo: Mini-challenge — TaskFlow REST API v1