OpenAPI/Swagger với springdoc-openapi — auto-generate API doc

openapi: 3.1.0
info:
  title: Order API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDto'
        '404':
          description: Order not found
components:
  schemas:
    OrderDto:
      type: object
      properties:
        id: { type: integer, format: int64 }
        customer: { type: string }
        total: { type: number }

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

[Swagger UI]
├── Order API (1.0.0)
│   ├── GET /api/v1/orders                  List orders
│   │   ├── Parameters: page, size, status
│   │   └── Responses: 200, 400
│   ├── GET /api/v1/orders/{id}             Get order by ID
│   ├── POST /api/v1/orders                 Create order
│   ├── PUT /api/v1/orders/{id}             Update order
│   └── DELETE /api/v1/orders/{id}          Delete order
└── Schemas
    ├── OrderRequest
    ├── OrderDto
    └── ProblemDetail

@Operation(
    summary = "Get order by ID",
    description = "Retrieves order details by its unique ID. Returns 404 if order not found.",
    tags = {"Orders"}
)
@GetMapping("/orders/{id}")
public OrderDto get(@PathVariable Long id) { ... }

@GetMapping("/orders")
public List<OrderDto> list(
    @Parameter(description = "Filter by status", example = "ACTIVE")
    @RequestParam(required = false) OrderStatus status,

    @Parameter(description = "Page number (0-indexed)", example = "0")
    @RequestParam(defaultValue = "0") int page,

    @Parameter(description = "Page size (1-100)", example = "20")
    @RequestParam(defaultValue = "20") int size
) { ... }

@Schema(description = "Order request payload")
public record OrderRequest(

    @Schema(description = "Customer name", example = "Alice", minLength = 2, maxLength = 100)
    @NotBlank
    String customer,

    @Schema(description = "Order total in VND", example = "99.99", minimum = "0.01")
    @NotNull @Positive
    BigDecimal total,

    @Schema(description = "Delivery date (ISO format)", example = "2026-04-20")
    @NotNull @Future
    LocalDate deliveryDate,

    @Schema(description = "Order items", minItems = 1, maxItems = 100)
    @NotEmpty @Size(max = 100)
    @Valid
    List<OrderItem> items
) {}

@Operation(summary = "Create order")
@ApiResponses({
    @ApiResponse(responseCode = "201", description = "Order created",
                 content = @Content(schema = @Schema(implementation = OrderDto.class))),
    @ApiResponse(responseCode = "400", description = "Validation failed",
                 content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
    @ApiResponse(responseCode = "409", description = "Duplicate order"),
    @ApiResponse(responseCode = "500", description = "Internal error")
})
@PostMapping("/orders")
public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req) { ... }

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("OLHub TaskFlow API")
                .version("v1.0")
                .description("REST API for TaskFlow project management")
                .contact(new Contact()
                    .name("OLHub Engineering")
                    .email("[email protected]")
                    .url("https://docs.olhub.org"))
                .license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0")))
            .servers(List.of(
                new Server().url("https://api.olhub.org").description("Production"),
                new Server().url("https://staging.olhub.org").description("Staging"),
                new Server().url("http://localhost:8080").description("Local dev")
            ))
            .externalDocs(new ExternalDocumentation()
                .description("Full API documentation")
                .url("https://docs.olhub.org"));
    }
}

springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
    tryItOutEnabled: true
    filter: true
    deepLinking: true
  show-actuator: false                # exclude actuator endpoints from docs
  packages-to-scan: com.olhub.api      # chi scan package nay
  paths-to-match: /api/**              # chi match URL pattern

@Configuration
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    in = SecuritySchemeIn.HEADER
)
public class OpenApiConfig {
    // ...
}

// Apply per controller
@SecurityRequirement(name = "bearerAuth")
@RestController
@RequestMapping("/api/orders")
public class OrderController { ... }

// Hoac global
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
        .components(new Components()
            .addSecuritySchemes("bearerAuth",
                new SecurityScheme()
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")));
}

@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 = "Read access"),
                @OAuthScope(name = "write", description = "Write access")
            }
        )
    )
)

@Configuration
public class GroupedOpenApiConfig {

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

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
            .group("admin")
            .pathsToMatch("/api/admin/**")
            .build();
    }

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

// Method-level
@Hidden
@GetMapping("/internal/admin")
public ... internal() { ... }

// Class-level
@Hidden
@RestController
public class InternalController { ... }

springdoc:
  packages-to-exclude: com.olhub.internal
  paths-to-exclude: /internal/**

springdoc:
  show-actuator: false

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

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

# application-dev.yml
springdoc:
  api-docs:
    enabled: true

@Configuration
public class SecurityConfig {

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

# CI/CD pipeline
curl http://localhost:8080/v3/api-docs > openapi-v1.2.3.yaml
git add docs/api/openapi-v1.2.3.yaml
git commit -m "Snapshot API spec for v1.2.3"

Developer code @RestController
    → springdoc auto-generate spec
    → Frontend đọc spec, implement

Designer write OpenAPI spec
    → Generator sinh interface Spring + DTO
    → Backend implement interface
    → Frontend đọc spec, implement song song

<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.api.generated</apiPackage>
                <modelPackage>com.olhub.api.generated.model</modelPackage>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>
                    <useSpringBoot3>true</useSpringBoot3>
                    <useJakartaEe>true</useJakartaEe>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

@RestController
public class OrderController implements OrdersApi {
    @Override
    public ResponseEntity<OrderDto> getOrder(Long id) {
        return ResponseEntity.ok(orderService.findById(id));
    }
}