OpenAPI¶

OpenAPI contract của Code To UML nằm tại docs/api-docs.yaml. Đây là nguồn mô tả chính thức cho HTTP API và có thể được dùng để đọc contract, kiểm tra thay đổi hoặc tạo client.

1. Mở contract¶

Khi website được build, file YAML được phát hành cùng bộ tài liệu. Có thể mở hoặc tải file từ liên kết trên để:

Mở bằng công cụ đọc OpenAPI 3.1 như Swagger Editor hoặc Redoc;
Kiểm tra contract khi phát triển client;
Tạo client hoặc type definitions bằng công cụ hỗ trợ OpenAPI 3.1;
So sánh thay đổi contract giữa các release.

Các ví dụ gọi API bằng HTTP nằm trong API Integration.

2. Phạm vi contract¶

YAML xác định:

Local và Production Gateway;
public route và route yêu cầu HTTP Bearer token;
Kroki-compatible POST, universal JSON API và encoded GET;
renderer catalog, theme catalog và option validation;
health, metrics, MIME type, response header và error schema.

Danh sách renderer, format và capability thực tế được lấy từ GET /api/diagram-types. Runtime catalog có thể thay đổi theo cấu hình server, đặc biệt khi Pydia hoặc browser companions được bật hay tắt.

3. Sử dụng contract¶

Dùng validator hỗ trợ OpenAPI 3.1 để kiểm tra file trước khi phát hành. Khi tạo client, chọn generator hỗ trợ OpenAPI 3.1 và kiểm tra request đại diện trên Local Gateway. Cách chọn endpoint, xác thực và xử lý response được trình bày trong API Integration.

4. Cập nhật contract¶

Khi HTTP API thay đổi:

Cập nhật docs/api-docs.yaml, source và automated test tương ứng.
Validate contract bằng công cụ hỗ trợ OpenAPI 3.1.
Chạy request đại diện qua Local Gateway.
Cập nhật API Integration nếu cách sử dụng của client thay đổi.