From 071e3562ea1ef3c70f92c489632cbd24a6ff527d Mon Sep 17 00:00:00 2001 From: Jarvis Date: Tue, 8 Apr 2025 12:14:39 +0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Add=20Vietnamese=20translation?= =?UTF-8?q?=20for=20`docs/vi/docs/tutorial/metadata.md`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/vi/docs/tutorial/metadata.md | 120 ++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 docs/vi/docs/tutorial/metadata.md diff --git a/docs/vi/docs/tutorial/metadata.md b/docs/vi/docs/tutorial/metadata.md new file mode 100644 index 000000000..ee98e95b0 --- /dev/null +++ b/docs/vi/docs/tutorial/metadata.md @@ -0,0 +1,120 @@ +# Metadata và URLs tài liệu + +Bạn hoàn toàn có thể tùy chỉnh các cấu hình metadata trong ứng dụng **FastAPI** của mình. + +## Metadata cho API + +Bạn có thể thiết lập các trường sau đây, chúng được sử dụng trong đặc tả OpenAPI và giao diện tài liệu API tự động: + +| Tham số | Kiểu | Mô tả | +|------------|------|-------------| +| `title` | `str` | Tiêu đề của API. | +| `summary` | `str` | Tóm tắt ngắn gọn của API. Đã có sẵn kể từ OpenAPI 3.1.0, FastAPI 0.99.0. | +| `description` | `str` | Mô tả ngắn gọn của API. Nó có thể sử dụng Markdown. | +| `version` | `string` | Phiên bản của API. Đây là phiên bản từ ứng dụng của bạn, không phải của OpenAPI. Ví dụ: `2.5.0`. | +| `terms_of_service` | `str` | URL đến Điều khoản dịch vụ của API. Nếu cung cấp, trường này phải là URL. | +| `contact` | `dict` | Thông tin liên hệ cho API được cung cấp. Nó có thể bao gồm một số trường sau.
contact Các trường
Tham sốKiểuMô tả
namestrTên nhận dạng của người liên hệ/tổ chức.
urlstrURL chỉ đến thông tin liên hệ. PHẢI là định dạng URL.
emailstrĐịa chỉ email của người liên hệ/tổ chức. PHẢI là định dạng email.
| +| `license_info` | `dict` | Thông tin chứng chỉ của API được cung cấp. Nó có thể bao gồm một số trường sau.
license_info Các trường
Tham sốKiểuMô tả
namestrBẮT BUỘC (Nếu có một license_info được thiết lập). Tên chứng chỉ của API được sử dụng.
identifierstrMột biểu thức giấy phép SPDX cho API. Trường identifier và trường url loại trừ lẫn nhau (không thể dùng đồng thời). Có sẵn từ OpenAPI 3.1.0, FastAPI 0.99.0.
urlstrURL đến giấy phép được sử dụng cho API. PHẢI ở định dạng URL.
| + +Bạn có thể thiết lập chúng như sau: + +{* ../../docs_src/metadata/tutorial001.py hl[3:16, 19:32] *} + +/// tip + +Bạn có thể viết Markdown trong trường `description` và nó sẽ được hiển thị ở giao diện tài liệu API tự động. + +/// + +Với cấu hình này, giao diện tài liệu API tự động sẽ trông như thế này: + + + +## License identifier + +Kể từ OpenAPI 3.1.0 và FastAPI 0.99.0, bạn cũng có thể thiết lập `license_info` với `identifier` thay vì `url`. + +Ví dụ: + +{* ../../docs_src/metadata/tutorial001_1.py hl[31] *} + +## Metadata cho tags + +Bạn cũng có thể thêm metadata bổ sung cho các tags khác nhau được sử dụng để nhóm các path operations của bạn với tham số `openapi_tags`. + +Nó lấy một danh sách chứa một dictionary cho mỗi tag. + +Mỗi dictionary có thể chứa: + +* `name` (**bắt buộc**): một `str` với tên tag giống như khi bạn sử dụng trong tham số `tags` của các *path operations* và `APIRouter`s. +* `description`: một `str` với mô tả ngắn cho tag. Nó có thể sử dụng Markdown và sẽ được hiển thị trong giao diện tài liệu. +* `externalDocs`: một `dict` mô tả tài liệu bên ngoài với: + * `description`: một `str` với mô tả ngắn cho tài liệu bên ngoài. + * `url` (**bắt buộc**): một `str` với URL cho tài liệu bên ngoài. + +### Tạo metadata cho tags + +Hãy thử điều đó trong ví dụ với tags `users` và `items`. + +Tạo metadata cho tags và chuyển nó đến tham số `openapi_tags`: + +{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *} + +Lưu ý rằng bạn có thể sử dụng Markdown trong các mô tả, ví dụ "login" sẽ được hiển thị in đậm (**login**) và "fancy" sẽ được hiển thị in nghiêng (_fancy_). + +/// tip + +Bạn không cần thêm metadata cho tất cả các tags mà bạn sử dụng. + +/// + +### Sử dụng tags của bạn + +Sử dụng tham số `tags` với các *path operations* (và `APIRouter`s) để gán chúng cho các tags khác nhau: + +{* ../../docs_src/metadata/tutorial004.py hl[21,26] *} + +/// info + +Đọc thêm về tag trong phần [Cấu hình Path Operations](path-operation-configuration.md#tags){.internal-link target=_blank}. + +/// + +### Kiểm tra tài liệu + +Bây giờ, nếu bạn kiểm tra tài liệu, chúng sẽ hiển thị tất cả các metadata bổ sung: + + + +### Thứ tự của tags + +Thứ tự của mỗi dictionary metadata tag cũng xác định thứ tự hiển thị trong giao diện tài liệu. + +Ví dụ, mặc dù `users` sẽ đứng sau `items` theo thứ tự bảng chữ cái, nhưng nó được hiển thị trước chúng, vì chúng ta đã thêm metadata của chúng nó làm dictionary đầu tiên trong danh sách. + +## URL OpenAPI + +Mặc định, schema OpenAPI được phục vụ tại `/openapi.json`. + +Nhưng bạn có thể cấu hình nó với tham số `openapi_url`. + +Ví dụ, để đặt nó được phục vụ tại `/api/v1/openapi.json`: + +{* ../../docs_src/metadata/tutorial002.py hl[3] *} + +Nếu bạn muốn vô hiệu hóa hoàn toàn schema OpenAPI hoàn toàn, bạn có thể đặt `openapi_url=None`, điều đó cũng sẽ tắt các giao diện tài liệu sử dụng nó. + +## URL tài liệu + +Bạn có thể cấu hình hai giao diện tài liệu được tích hợp: + +* **Swagger UI**: được phục vụ tại `/docs`. + * Bạn có thể đặt URL của nó với tham số `docs_url`. + * Bạn có thể vô hiệu hóa nó bằng cách đặt `docs_url=None`. +* **ReDoc**: được phục vụ tại `/redoc`. + * Bạn có thể đặt URL của nó với tham số `redoc_url`. + * Bạn có thể vô hiệu hóa nó bằng cách đặt `redoc_url=None`. + +Ví dụ, để đặt Swagger UI được phục vụ tại `/documentation` và vô hiệu hóa ReDoc: + +{* ../../docs_src/metadata/tutorial003.py hl[3] *}