Tài liệu API (OpenAPI)

govex-cloud-apidoc chuẩn hoá tài liệu OpenAPI cho service Govex Cloud: dựng tài liệu từ nhóm property springdoc.*, gom nhóm API theo tag cho Redoc và phục vụ trang xem tài liệu tĩnh api-docs.html. Thêm dependency khi service cần công bố tài liệu API thống nhất với các service khác trong hệ thống.

Khi nào sử dụng

• Service có REST API cần tài liệu OpenAPI/Redoc dùng chung một định dạng.
• Cần gom nhóm API theo nghiệp vụ để sidebar Redoc gọn gàng, dễ tra cứu.
• Cần cấu hình Info, servers, extensions của tài liệu qua file cấu hình thay vì hardcode trong code.

Cài đặt

Thêm dependency (không khai version — version do BOM quản lý, xem Cài đặt):

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-apidoc</artifactId>
</dependency>

Dependency kéo theo springdoc-openapi bản WebMVC và tự bật khi có property springdoc.api-docs.enabled (mặc định bật).

Cấu hình

Property	Mô tả	Mặc định
springdoc.api-docs.enabled	Bật/tắt auto-configuration của dependency	true
springdoc.info.*	Thông tin Info của OpenAPI: title, description, version, contact, license...	rỗng — dependency tự điền {spring.application.name} Service
springdoc.servers	Danh sách Server (URL, description) hiển thị trong tài liệu	rỗng
springdoc.external-docs.*	Tài liệu tham chiếu bên ngoài (url, description)	rỗng
springdoc.extensions	Extension key-value gắn vào tài liệu OpenAPI	rỗng
springdoc.components.*	Thành phần OpenAPI dùng chung (schemas, responses, parameters...)	rỗng
springdoc.paths	Path bổ sung cho tài liệu	rỗng
springdoc.group-configs[*].group, springdoc.group-configs[*].info.*	Cấu hình Info theo nhóm API khai báo trong properties	rỗng

Khi springdoc.info.title/description để trống, dependency tự điền tên service từ spring.application.name.

Sử dụng

Cấu hình tài liệu bằng YAML

springdoc:
  info:
    title: Hệ thống quản lý
    description: Tài liệu API nội bộ
  servers:
    - url: https://api.example.vn
      description: Môi trường vận hành
  extensions:
    x-audience: internal

Gom nhóm API theo controller

@TagGroup(value = "Quản lý người dùng", sortOrder = 10)
@RestController
@RequestMapping("/api/v1/users")
public class UserController { }

@TagGroup chỉ gắn trên class controller, gồm value (tên nhóm) và sortOrder (thứ tự hiển thị, mặc định 0). Operation không gắn @TagGroup rơi vào nhóm mặc định Chung.

Xem tài liệu

Trang Redoc được phục vụ tại {context-path}/api-docs.html — dùng đúng context path của service (ví dụ service đặt context path /user thì mở /user/api-docs.html).

Lưu ý

• Dependency dành cho service Spring MVC; cần spring-boot-starter-web trên classpath.
• Tài liệu OpenAPI do springdoc sinh ra; dependency chỉ bổ sung bean OpenAPI, cơ chế gom nhóm tag và trang Redoc tĩnh.
• Nhóm Chung là nhóm mặc định cho operation không gắn @TagGroup; extension x-tagGroups chỉ được thêm khi tài liệu có nhiều hơn một nhóm.
• Trong package org.springdoc.core.service có lớp thay thế logic dựng parameter của springdoc; khi nâng cấp phiên bản springdoc-openapi cần kiểm tra lại tương thích/thứ tự classpath.
• springdoc.group-configs đã được khai báo trong properties nhưng chưa được dependency dùng để sinh nhóm — gom nhóm hiện thực hiện qua @TagGroup.