OpenAPI nâng cao — security scheme, GroupedOpenApi, ẩn endpoint, production deploy, API-first

TL;DR: Bốn kỹ thuật nâng cao của springdoc: (1) @SecurityScheme khai báo JWT/OAuth2 trong spec — Swagger UI hiển thị nút "Authorize" để inject token vào mọi request "Try it out"; (2) GroupedOpenApi tách doc thành nhiều nhóm độc lập (public/admin/internal), mỗi nhóm có spec riêng tại /v3/api-docs/{group}; (3) @Hidden hoặc springdoc.paths-to-exclude ẩn endpoint nội bộ khỏi spec public; (4) production nên disable hoặc auth-protect Swagger UI — không để public vì lộ toàn bộ API surface. Cuối bài: so sánh API-first (design spec trước → backend + frontend implement song song) vs code-first (springdoc default) — biết chọn đúng theo quy mô team.

Bài trước (OpenAPI & springdoc) đã bóc cơ chế auto-generate spec và các annotation customize cơ bản (@Operation, @Schema, @ApiResponses). Bài này đi tiếp bốn bài toán thực tế mà mọi production app đều gặp: bảo mật doc, chia nhóm doc, ẩn endpoint nội bộ, và triết lý thiết kế API-first.

1. Security scheme — inject token vào Swagger UI

Vì sao cần khai báo security scheme trong spec?

Khi app có JWT authentication, developer cần test endpoint protected từ Swagger UI. Không có security scheme, UI chỉ gửi request bare — server từ chối 401. Developer phải mở Postman, copy-paste header thủ công — mất thời gian, dễ sai.

Security scheme là phần khai báo trong OpenAPI spec mô tả cơ chế xác thực mà API yêu cầu: loại scheme (HTTP Bearer, OAuth2, API Key...), vị trí token (header, cookie, query), và format (JWT, opaque). Khi spec có phần này, Swagger UI render nút "Authorize" — user paste token một lần, mọi "Try it out" sau đó tự inject header Authorization: Bearer <token>.

JWT Bearer scheme

// Khai bao scheme o cap @Configuration — springdoc doc vao components.securitySchemes
@Configuration
@SecurityScheme(
    name = "bearerAuth",                     // ten de ref trong @SecurityRequirement
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",                    // chi doc, khong validate
    in = SecuritySchemeIn.HEADER,
    description = "JWT token tu /api/auth/login"
)
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("TaskFlow API").version("v1.0"))
            // Ap dung global cho moi endpoint
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
    }
}

Khai báo trên thêm vào spec JSON tại components.securitySchemes:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []     # global requirement

Endpoint login không cần auth — override global bằng @SecurityRequirements rỗng:

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

    @SecurityRequirements   // empty — override global, khong can token
    @PostMapping("/login")
    public TokenResponse login(@Valid @RequestBody LoginRequest req) { ... }

    @SecurityRequirements   // tuong tu
    @PostMapping("/register")
    public UserDto register(@Valid @RequestBody RegisterRequest req) { ... }
}

// Protected controller — ke thua global hoac explicit
@SecurityRequirement(name = "bearerAuth")
@RestController
@RequestMapping("/api/projects")
public class ProjectController { ... }

Luồng sử dụng trong UI:

flowchart LR
  A["Mo /swagger-ui.html"] --> B["Click nut Authorize"]
  B --> C["Paste JWT token"]
  C --> D["Click Authorize trong modal"]
  D --> E["Try it out bat ky endpoint"]
  E --> F["UI tu inject<br/>Authorization: Bearer token"]
  F --> G["Server nhan request co token hop le"]

OAuth2 Authorization Code scheme

Khi app dùng OAuth2/OIDC (ví dụ tích hợp Google, Keycloak), khai báo scheme phức tạp hơn — spec mô tả đầy đủ các URL của auth server để UI thực hiện flow authorization code:

@SecurityScheme(
    name = "oauth2",
    type = SecuritySchemeType.OAUTH2,
    flows = @OAuthFlows(
        authorizationCode = @OAuthFlow(
            authorizationUrl = "https://auth.olhub.org/oauth2/authorize",
            tokenUrl = "https://auth.olhub.org/oauth2/token",
            scopes = {
                @OAuthScope(name = "read",  description = "Doc du lieu"),
                @OAuthScope(name = "write", description = "Tao va sua du lieu")
            }
        )
    )
)

UI redirect user sang auth server, nhận code callback, exchange lấy token — toàn bộ OAuth2 flow chạy trong trình duyệt qua Swagger UI.

2. GroupedOpenApi — chia doc thành nhiều nhóm

Vì sao cần nhóm tách biệt?

App lớn có nhiều loại endpoint: public API cho khách hàng, admin API cho internal team, internal API cho service-to-service call. Nếu gộp hết vào một spec, developer public nhìn thấy toàn bộ admin endpoint — nguy hiểm về thông tin. Hơn nữa, spec khổng lồ (200+ endpoint) khó điều hướng.

GroupedOpenApi là bean springdoc tạo ra một spec độc lập cho một tập endpoint, filter theo path pattern hoặc package. Mỗi nhóm có URL spec riêng tại /v3/api-docs/{groupName}. Swagger UI hiển thị dropdown "Select Definition" — user chọn nhóm.

@Configuration
public class OpenApiGroupConfig {

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

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

    @Bean
    public GroupedOpenApi internalApi() {
        return GroupedOpenApi.builder()
            .group("internal")
            .displayName("Service-to-Service")
            .pathsToMatch("/internal/**")
            .build();
    }
}

Kết quả — ba spec endpoint độc lập:

flowchart TB
  subgraph CTRL["Controllers"]
    direction TB
    P1["/api/v1/** -- public"]
    P2["/api/admin/** -- admin"]
    P3["/internal/** -- service"]
  end
  subgraph GRP["GroupedOpenApi beans"]
    direction TB
    G1["group: public"]
    G2["group: admin"]
    G3["group: internal"]
  end
  subgraph SPEC["Spec URLs"]
    direction TB
    E1["GET /v3/api-docs/public"]
    E2["GET /v3/api-docs/admin"]
    E3["GET /v3/api-docs/internal"]
  end
  P1 --> G1 --> E1
  P2 --> G2 --> E2
  P3 --> G3 --> E3

Swagger UI có dropdown "Select Definition" top-right — chọn nhóm nào, spec tương ứng nhóm đó được load. Mỗi nhóm có thể có security scheme, server, info title riêng qua addOpenApiCustomizer.

Bảo vệ selectively theo group — production best practice:

// Chỉ public spec không cần auth; admin + internal yêu cầu ROLE_ADMIN
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/v3/api-docs/public").permitAll()
        .requestMatchers("/v3/api-docs/admin", "/v3/api-docs/internal")
            .hasRole("ADMIN")
        .anyRequest().authenticated()
    );
    return http.build();
}

3. Ẩn endpoint khỏi spec — @Hidden và config exclude

Không phải mọi endpoint đều cần xuất hiện trong doc. Actuator endpoints, debug endpoints, migration scripts endpoint — tất cả nên ẩn khỏi spec trước khi deploy.

@Hidden — ẩn chọn lọc

// An toan bo mot endpoint
@Hidden
@GetMapping("/internal/health-check-verbose")
public Map<String, Object> verboseHealth() { ... }

// An toan bo mot controller
@Hidden
@RestController
@RequestMapping("/debug")
public class DebugController {
    // Khong co endpoint nao trong class nay xuat hien trong spec
}

@Hidden từ io.swagger.v3.oas.annotations — springdoc skip endpoint này khi build spec, dù controller vẫn hoạt động bình thường ở runtime.

Config exclude — ẩn theo pattern

Khi cần ẩn nhiều endpoint theo pattern, dùng config thay vì annotate từng method:

springdoc:
  paths-to-exclude: /internal/**, /debug/**, /actuator/**
  packages-to-exclude: com.olhub.internal, com.olhub.debug
  show-actuator: false   # Boot actuator endpoints luon an

4. Production deploy — tắt hay bảo vệ Swagger UI?

Vì sao đây là quyết định bảo mật, không phải preference?

Swagger UI trên production public có nghĩa: bất kỳ ai trên internet cũng thấy toàn bộ API surface của hệ thống — mọi endpoint, parameter, schema, constraint validation. Đây là thông tin attacker dùng để:

• Enumerate attack surface: biết chính xác endpoint nào tồn tại, method nào hợp lệ, format payload ra sao.
• Leak validation rule: spec expose constraint (minLength=8, pattern=...) giúp attacker design payload bypass hoặc brute-force có hướng.
• Try-it-out as probe tool: "Try it out" gửi request thật đến production server — attacker dùng UI như công cụ fuzzing miễn phí.

Ba chiến lược, mức bảo vệ tăng dần:

Option 1 — Disable hoàn toàn trong production:

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

Doc public được generate từ snapshot staging, host trên CDN riêng (Redocly, Stoplight Elements, GitHub Pages). App server không expose spec endpoint nào.

Option 2 — Auth-protect (recommended khi cần internal access):

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers(
            "/v3/api-docs/**",
            "/swagger-ui/**",
            "/swagger-ui.html")
        .hasRole("DEVELOPER")        // chỉ internal team
        .anyRequest().authenticated()
    );
    return http.build();
}

Internal developer login với account DEVELOPER role mới xem được doc. Không public.

Option 3 — Path obscurity (yếu nhất, không recommend):

springdoc:
  swagger-ui:
    path: /internal-docs-k9x2q   # URL kho doan
  api-docs:
    path: /internal-spec-k9x2q

Security through obscurity — không phải defense thật sự. Attacker scan phát hiện được.

Khuyến nghị cho TaskFlow capstone:

Snapshot spec trong CI/CD

# .github/workflows/deploy.yml (đoạn them vao sau build)
- name: Snapshot OpenAPI spec
  run: |
    # Chay app staging, lay spec
    curl -f http://staging.olhub.org/v3/api-docs > docs/api/openapi-v${{ env.VERSION }}.json
    git add docs/api/openapi-v${{ env.VERSION }}.json

Track diff giữa version bằng openapi-diff — phát hiện breaking change (xoá endpoint, đổi field bắt buộc).

5. API-first vs code-first — trade-off theo quy mô team

Hai workflow thiết kế API

Đây không phải lựa chọn đúng-sai — là lựa chọn phù hợp ngữ cảnh.

Code-first (springdoc default): developer code @RestController trước, springdoc auto-generate spec từ annotation. Spec là output của quá trình implement.

API-first: team design OpenAPI spec (openapi.yaml) trước — đây là contract. Tool sinh interface Java từ spec. Backend implement interface. Frontend dev song song với mock server đọc spec.

Vì sao API-first ra đời — bài toán parallel team

Code-first có vấn đề căn bản: frontend phải đợi backend code xong mới có spec để implement. Với team 2-3 người, đây chấp nhận được. Với team 10+ người gồm frontend và backend riêng, mất 1-2 tuần đợi backend scaffold là lãng phí.

API-first giải quyết bằng cách đảo thứ tự: spec ra đời trước, cả hai team dùng spec làm nguồn sự thật. Frontend dev với mock server (Prism chạy spec như real server), backend implement interface do generator sinh ra từ spec. Hai team song song từ ngày 1.

flowchart TB
  subgraph CF["Code-first (springdoc)"]
    direction LR
    CF1["Backend code controller"] --> CF2["springdoc gen spec"] --> CF3["Frontend nhan spec"]
    CF3 --> CF4["Frontend implement"]
    style CF3 fill:#fef3c7,stroke:#f59e0b
  end
  subgraph AF["API-first"]
    direction LR
    AF1["Design openapi.yaml"] --> AF2["Generator sinh interface"]
    AF1 --> AF3["Prism mock server"]
    AF2 --> AF4["Backend implement"]
    AF3 --> AF5["Frontend dev voi mock"]
    AF4 -.->|"tich hop"| AF5
  end

So sánh trade-off

API-first với openapi-generator-maven-plugin

<!-- pom.xml -->
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.10.0</version>
    <executions>
        <execution>
            <goals><goal>generate</goal></goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>com.olhub.generated.api</apiPackage>
                <modelPackage>com.olhub.generated.model</modelPackage>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>      <!-- chi sinh interface, khong impl -->
                    <useSpringBoot3>true</useSpringBoot3>
                    <useJakartaEe>true</useJakartaEe>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Generator sinh interface ProjectsApi từ spec. Controller implement interface — nếu spec thay đổi, compile fail ngay:

// Generated tu spec — KHONG edit file nay
public interface ProjectsApi {
    ResponseEntity<ProjectDto> getProject(@PathVariable Long id);
    ResponseEntity<ProjectDto> createProject(@Valid @RequestBody ProjectRequest req);
    ResponseEntity<Void> deleteProject(@PathVariable Long id);
}

// Controller implement interface — code do team viet
@RestController
public class ProjectController implements ProjectsApi {

    @Override
    public ResponseEntity<ProjectDto> getProject(Long id) {
        return ResponseEntity.ok(projectService.findById(id));
    }

    // ... implement cac method khac
}

Pitfall thực tế

❌ Nhầm 1 — @Hidden là security control:

// SAI: tuong rang @Hidden bao ve endpoint
@Hidden
@GetMapping("/admin/delete-all")
public void deleteAll() { ... }

@Hidden chỉ ẩn khỏi doc. Endpoint vẫn hoạt động — ai đoán được URL vẫn gọi được. Bảo vệ thật sự cần @PreAuthorize hoặc Spring Security URL rule.

✅ Dùng @Hidden để giữ doc gọn, dùng security annotation/config để bảo vệ thật sự.

❌ Nhầm 2 — GroupedOpenApi không filter, spec vẫn expose hết:

// SAI: group khong co pathsToMatch -> include tat ca endpoint
@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
        .group("public")
        .build();  // thieu pathsToMatch
}

✅ Luôn khai báo pathsToMatch hoặc packagesToScan rõ ràng cho mỗi group.

❌ Nhầm 3 — Để security scheme global nhưng quên exempt public endpoint:

Khi dùng .addSecurityItem(new SecurityRequirement().addList("bearerAuth")) global, endpoint login cũng yêu cầu token trong spec — Swagger UI lock nút "Try it out" cho /auth/login. Phải thêm @SecurityRequirements rỗng cho endpoint không cần auth.

Liên hệ các bài khác

• OpenAPI & springdoc: bài trước — cơ chế auto-generate spec, annotation @Operation/@Schema/@ApiResponses. Bài này là layer nâng cao lên trên nền đó.
• Mini-challenge TaskFlow v1: capstone module — áp dụng toàn bộ kiến thức module 03 bao gồm security scheme JWT và config production. Thực hành ngay sau bài này.
• Exception handling và validation (các bài trước trong module 03): spec tự document ProblemDetail response từ @RestControllerAdvice — thấy rõ liên hệ khi setup @ApiResponses cho error codes.

Tóm tắt

• Security scheme (@SecurityScheme + @SecurityRequirement) khai báo JWT/OAuth2 trong spec — Swagger UI hiển thị nút "Authorize", inject token tự động vào mọi "Try it out". Endpoint public override bằng @SecurityRequirements rỗng.
• GroupedOpenApi tách spec thành nhiều nhóm (public/admin/internal) — mỗi nhóm có URL spec riêng /v3/api-docs/{group}, có thể auth-protect chọn lọc.
• @Hidden ẩn endpoint khỏi spec (không phải khỏi truy cập). Config springdoc.paths-to-exclude ẩn theo pattern. @Hidden không phải security control.
• Production: disable Swagger UI hoặc auth-protect. Public doc host trên CDN từ snapshot staging. Không expose spec endpoint public trên app server production.
• Code-first (springdoc): spec là output của code — phù hợp team nhỏ, iteration nhanh. API-first (openapi-generator): spec là contract thiết kế trước — backend + frontend implement song song, phù hợp team lớn, API public.

Tự kiểm tra

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