Tài liệu API giúp nhóm frontend, di động dùng API dễ dàng. Thư viện springdoc-openapi tự sinh tài liệu theo chuẩn OpenAPI và trang Swagger UI để thử API.

35 phútTrung cấp
Bạn sẽ học được
  • Thêm springdoc-openapi
  • Swagger UI
  • Mô tả API bằng annotation
  • Cấu hình xác thực trong tài liệu

Cơ sở lý thuyết

Tài liệu API là hợp đồng giữa nhóm backend và các nhóm sử dụng (web, di động, đối tác). Hai cách tiếp cận:

  • Code-first: viết mã trước, công cụ (springdoc-openapi) phân tích controller, DTO, annotation để sinh đặc tả OpenAPI – tài liệu luôn khớp với mã.
  • Design-first / API-first: thiết kế đặc tả OpenAPI trước, các nhóm thống nhất, rồi sinh mã khung cho cả máy chủ và máy khách (openapi-generator).
  • OpenAPI 3 (trước đây là Swagger) mô tả đường dẫn, phương thức, tham số, lược đồ dữ liệu, mã phản hồi, phương thức bảo mật dạng YAML/JSON máy đọc được.
  • Từ đặc tả có thể sinh mã máy khách (TypeScript cho React, Kotlin cho Android), giảm lỗi gõ sai tên trường.

Cài đặt

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version><!-- phiên bản tương thích Spring Boot đang dùng --></version>
</dependency>

Mở http://localhost:8080/swagger-ui.html để xem và thử API; tài liệu JSON ở /v3/api-docs.

@Tag(name = "Sinh viên")
@Operation(summary = "Lấy sinh viên theo mã")
@ApiResponse(responseCode = "404", description = "Không tìm thấy")
@GetMapping("/{ma}")
SinhVienDto mot(@PathVariable String ma) { ... }

Ứng dụng thực tế

Bài toán: nhóm làm ứng dụng di động cần thư viện gọi API có kiểu dữ liệu đầy đủ. Sinh tự động từ đặc tả do Spring Boot xuất ra:

# Lấy đặc tả từ ứng dụng đang chạy
curl http://localhost:8080/v3/api-docs -o openapi.json

# Sinh mã máy khách TypeScript cho frontend React
npx @openapitools/openapi-generator-cli generate -i openapi.json -g typescript-fetch -o src/api

# Sinh mã máy khách Kotlin cho Android
npx @openapitools/openapi-generator-cli generate -i openapi.json -g kotlin -o android-client

Khi backend đổi API, chỉ cần sinh lại mã; lỗi không khớp sẽ lộ ra ngay lúc biên dịch ứng dụng thay vì khi người dùng sử dụng.

Thực hành
  1. Thêm Swagger UI cho dự án.
  2. Mô tả các API sinh viên bằng annotation.
  3. Xuất tài liệu và nhập vào Postman.
Tóm tắt bài học
  • springdoc sinh tài liệu OpenAPI tự động.
  • Swagger UI thử API trực tiếp.
  • Annotation bổ sung mô tả.