Tiêu chuẩn OpenAPI phiên bản 3.0.3 (OpenAPI Specification version 3.0.3) - Phần II 

Tiếp nối phần 1 với các khái niệm cơ bản cùng tổng quan đơn giản nhất về tiêu chuẩn OAS, phần 2 sẽ đi sâu hơn vào yếu tố đối tượng của tiêu chuẩn, đây là yếu tố chính giúp xây dựng các API mở cho người dùng. Phần 2 của bài viết sẽ phù hợp hơn nếu muốn tìm hiểu sâu và nắm bắt toàn bộ về tiêu chuẩn này.

 

Hình 1: mã nguồn xây dựng cho một API được xây dựng trên chuẩn OpenAPI

6. Đối tượng của OpenAPI

Trường

Kiểu data

Miêu tả

openapi

string

Là trường dữ liệu bắt buộc. Chuỗi này phải tuân thủ phiên bản ngữ nghĩa (Semantic ver) mà tiêu chuẩn OAS sử dụng. Giá trị “openapi” phải được sử dụng bằng các công cụ và máy chủ được nêu trong tài liệu để diễn giải. Giá trị này không không liên quan đến chuỗi API “info.version”

info

Info Object

Là trường dữ liệu bắt buộc. Giúp cung cấp siêu dữ liệu về API. Siêu dữ liệu có thể được sử dụng bằng công cụ theo yêu cầu.

server

[Server Object]

Là một mảng giá trị của đối tượng máy chủ giúp cung cấp thông tin kết nối đến máy chủ đích. Nếu thuộc tính “server” không được cung cấp hoặc là một mảng để trống thì giá trị mặc định sẽ là “Server Object” với giá trị “url” sẽ “/”

paths

Paths Object

Là trường dữ liệu bắt buộc. Cung cấp thông tin về các đường dẫn và hoạt động có sẵn cho API.

components

Components Object

Một phần tử để chứa các lược đồ khác nhau cho đặc tả.

security

[Security Requirement Object]

Tuyên bố về các cơ chế bảo mật có thể được sử dụng trên API. Danh sách các giá trị bao gồm các đối tượng yêu cầu bảo mật thay thế có thể được sử dụng. Chỉ một trong các đối tượng yêu cầu bảo mật cần được đáp ứng để cho phép một yêu cầu. Các hoạt động riêng lẻ có thể ghi đè định nghĩa này. Để làm cho bảo mật là tùy chọn, một yêu cầu bảo mật trống ( {}) có thể được bao gồm trong mảng.

tag

[Tag Object]

Danh sách các thẻ được đặc tả sử dụng với siêu dữ liệu bổ sung. Thứ tự của các thẻ có thể được sử dụng để phản ánh thứ tự của chúng bằng các công cụ phân tích cú pháp. Không phải tất cả các thẻ được sử dụng đều phải được khai báo. Các thẻ không được khai báo có thể được sắp xếp ngẫu nhiên hoặc dựa trên logic của công cụ. Mỗi tên thẻ trong danh sách phải là duy nhất.

externalDocs

External Documentation

Object

Tài liệu bên ngoài bổ sung.

7. Đối tượng Info

Đối tượng cung cấp siêu dữ liệu về API. Siêu dữ liệu có thể được máy chủ sử dụng nếu cần, và có thể được trình bày trong các công cụ chỉnh sửa hoặc tạo tài liệu để thuận tiện.

Trường

Kiểu data

Miêu tả

title

string

Là trường dữ liệu bắt buộc. Đây là nội dung của API

description

string

Đây là miêu tả ngắn gọn về API. Cú pháp CommonMark có thể được sử dụng để biểu diễn văn bản đa dạng thức.

termsOfServer

string string

URL của Điều khoản dịch vụ cho API và phải ở định dạng URL.

contact

Contact Object

Thông tin liên hệ cho API được tiếp xúc.

lincense

License Object

Thông tin giấy phép cho API được tiết lộ.

version

string

Là trường dữ liệu bắt buộc. Nêu rõ phiên bản của tài liệu OpenAPI (khác với phiên bản của tiêu chuẩn OAS và phiên bản triển khai API).

Hình 2: ví dụ về đối tượng info

8. Đối tượng Contact

Thông tin liên hệ cho API được tiếp xúc

Trường

Kiểu data

Miêu tả

name

string

Tên nhận dạng của người/ tổ chức liên hệ.

url

string

URL trỏ đến thông tin liên hệ và phải ở định dạng URL.

email

string

Địa chỉ email của người/ tổ chức liên hệ và phải ở định dạng địa chỉ email.

Hình 3: ví dụ về đối tượng contact

9. Đối tượng License

Để cung cấp thông tin giấy phép cho các API khác, đối tượng sẽ bao gồm:

Trường

Kiểu data

Miêu tả

name

string

Là trường dữ liệu bắt buộc. Tên loại giấy phép được sử dụng cho API.

url

string

URL của giấy phép được sử dụng cho API và phải ở định dạng URL.

Hình 4: ví dụ về đối tượng License

10. Đối tượng server

Các thông tin của đối tượng bao gồm:

Trường

Kiểu data

Miêu tả

url

string

Là trường dữ liệu bắt buộc. Một URL chỉ dẫn đến địa chỉ đích server. URL này hỗ trợ Biến máy chủ và có thể là tương đối, để chỉ ra rằng vị trí máy chủ có liên quan đến vị trí nơi tài liệu OpenAPI đang được cung cấp. Việc thay thế biến sẽ được thực hiện khi một biến được đặt tên trong {ngoặc }.

description

string

Một chuỗi tùy chọn mô tả máy chủ được chỉ định bởi URL. Cú pháp “CommonMark có thể được sử dụng để biểu diễn văn bản đa dạng ngữ nghĩa.

variables

Map[string, Server Variable Object]

Một ánh xạ giữa một tên biến và giá trị của nó. Giá trị được sử dụng để thay thế trong mẫu URL của máy chủ.

Hình 5: ví dụ về đối tướng server bao gồm nhiều máy chủ

11. Đối tượng variables của server

Trường

Kiểu data

Miêu tả

enum

[string]

Một bảng liệt kê các giá trị chuỗi sẽ được sử dụng nếu các tùy chọn thay thế là từ một tập hợp giới hạn. Mảng giá trị này không được để trống.

default

string

Là trường dữ liệu bắt buộc. Giá trị mặc định để sử dụng thay thế, giá trị này sẽ được gửi nếu giá trị thay thế không được cung cấp. Nếu giá trị  “enumđược xác định, giá trị trường này nên tồn tại trong các giá trị của enum.

description

string

Trường giá trị này là tùy chọn cho biến máy chủ. Cú pháp “CommonMark có thể được sử dụng để biểu diễn văn bản đa dạng thức.

12. Đối tượng Components

Đối tượng này có tác dụng giữ một tập hợp các đối tượng có thể tái sử dụng cho các khía cạnh khác nhau của OAS. Tất cả các đối tượng được xác định bên trong đối tượng thành phần sẽ không có hiệu lực trên API.

Trường

Kiểu data

Miêu tả

schemas

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Schema.

responses

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Response.

parameters

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Parameter.

examples

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Example.

requestBodies

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Request Body Objects.

headers

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Header.

sercuritySchemes

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Security Scheme.

links

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Link.

callbacks

Map[string, Schema Object| Reference Object]

Là giá trị được tái sử dụng cho đối tượng Callback.

Tất cả các lĩnh vực cố định tuyên bố trên là đối tượng mà phải sử dụng các phím phù hợp với biểu thức chính quy: (^[a-zA-Z0-9\.\-_]+$).

13. Đối tượng Paths

 Đối tượng Paths có tác dụng giữ các đường dẫn tương đối đến các điểm cuối riêng lẻ và hoạt động của chúng. Đường dẫn được nối vào URL từ đối tượng Server để tạo URL đầy đủ. Các đường dẫn có thể trống, do các ràng buộc ACL .

Trường

Kiểu data

Miêu tả

/{path}

Path Item Object

Mỗi đường dẫn thường đến một địa chỉ riêng lẻ. Tên trường phải bắt đầu bằng dấu gạch chéo lên (/). Đường dẫn được nối vào URL được mở rộng từ trường server của url để tạo URL đầy đủ. Tạo mẫu đường dẫn được cho phép. Khi các URL phù hợp, các đường dẫn cụ thể (không theo mẫu) sẽ được so sánh trước các đối tượng được tạo trước đó. Các đường dẫn không được để tên trùng nhau. Trong trường hợp so sánh không rõ ràng, tùy thuộc vào công cụ để quyết định sử dụng hay không.

14. Đối tượng Path Item

Mô tả các trường có sẵn trên một đường dẫn duy nhất. Đường dẫn có thể để trống do các ràng buộc ACL. Các trường của một đối tượng bao gồm:

Trường

Kiểu data

Miêu tả

$ref

string

Cho phép định nghĩa bên ngoài của mục đường dẫn này. Cấu trúc được tham chiếu phải ở định dạng Path Item.

summary

string

Là trường không bắt buộc, nhằm áp dụng cho tất cả các thao tác trong đường dẫn.

description

string

Là trường không bắt buộc, nằm áp dụng cho tất cả các thao tác trong đường dẫn này.

get

Operation Object

Giá trị định nghĩa GET trong Path

put

Operation Object

Giá trị định nghĩa PUT trong Path

post

Operation Object

Giá trị định nghĩa POST trong Path

delete

Operation Object

Giá trị định nghĩa DELETE trong Path

options

Operation Object

Giá trị định nghĩa OPTIONS trong Path

head

Operation Object

Giá trị định nghĩa HEAD trong Path

patch

Operation Object

Giá trị định nghĩa PATCH trong Path

trace

Operation Object

Giá trị định nghĩa TRACE trong Path

servers

[Server Object]

Một mảng giá trị “server” trong trường hợp thanh thế

parameters

[Parameter Object | Reference Object]

Danh sách các tham số có thể áp dụng cho tất cả các hoạt động được mô tả trong đường dẫn này. Các tham số này có thể được ghi đè ở mức hoạt động, nhưng không thể xóa ở đó. Danh sách KHÔNG ĐƯỢC bao gồm các tham số trùng lặp. Một tham số duy nhất được xác định bởi sự kết hợp của name location. Danh sách có thể sử dụng Reference Object để liên kết đến các tham số được xác định tại các thành phần / tham số của Đối tượng OpenAPI.

15. Đối tượng Operation

Đối tượng Operation bao gồm:

Trường

Kiểu data

Miêu tả

tags

string

Danh sách các thẻ để kiểm soát tài liệu API. Thẻ có thể được sử dụng để phân nhóm hợp lý các hoạt động theo tài nguyên.

summary

string

Một bản tóm tắt ngắn về những gì hoạt động.

description

string

Giải thích chi tiết về hành vi hoạt động. Cú pháp CommonMark có thể được sử dụng để biểu diễn văn bản đa dạng thức.

externalDocs

External Documentation Object

Tài liệu bên ngoài bổ sung cho hoạt động này.

operationId

string

Chuỗi duy nhất được sử dụng để xác định hoạt động. Id phải là duy nhất trong số tất cả các hoạt động được mô tả trong API. Giá trị operationId phân biệt chữ hoa chữ thường. Các công cụ và thư viện có thể sử dụng operationId để xác định duy nhất một thao tác, do đó, khuyến cáo tuân theo các quy ước đặt tên chương trình phổ biến.

parameters

[Parameter Object | Reference Object]

Danh sách các thông số có thể áp dụng cho Operation được khai báo. Nếu một tham số đã được xác định tại mục Path item , thì định nghĩa mới sẽ ghi đè tham số đó nhưng không bao giờ có thể loại xóa bỏ nó. Danh sách không được chấp nhận bao gồm các tham số trùng lặp. Một tham số duy nhất được xác định bởi sự kết hợp của namelocation. Danh sách có thể sử dụng Reference Object để liên kết đến các tham số được xác định tại các components/ parameter của đối tượng OpenAPI Object.

requestBody

[Request Body Object | Reference Object]

“requestBody” được hỗ trợ trong các phương thức HTTP mà đặc điểm kỹ thuật HTTP 1.1 Tài liệu RFC7231 đã xác định rõ ràng ngữ nghĩa cho các nôi dụng được yêu cầu. Trong các trường hợp khác khi thông số HTTP không rõ ràng, “requestBody” sẽ bị bỏ qua.

responses

Responses Object

Là trường dữ liệu bắt buộc. Là danh sách các responses có thể xảy ra khi chúng được trả về sau khi thực hiện các tháo tác tương đương.

callbacks

Map[string, Callback Object | Reference Object]

Một bản đồ điển thị các lệnh gọi lại ngoài băng tần có thể liên quan đến hoạt động chính của operation. Đây là định danh duy nhất và các giá trị là duy nhất. mổ tả một yêu cầu có thể được khởi tạo bởi nhà cung cấp API và các phản hồi dự kiến.

deprecated

boolean

Đây là một giá trị không còn được dùng nữa. người viết nên hạn chế sử dụng để khai báo. Giá trị mặc định là false.

security

[Security Requirement Object]

Tuyên bố về các cơ chế bảo mật có thể được sử dụng cho hoạt động này. Danh sách các giá trị bao gồm các đối tượng yêu cầu bảo mật. Mỗi đối tượng là có yêu cầu bảo mật duy nhất. Để làm cho bảo mật là tùy chọn, một yêu cầu bảo mật trống ({}) có thể được bao gồm trong mảng. Định nghĩa này ghi đè mọi cấp cao nhất đã khai báo giá trị “security. Để loại bỏ một khai báo bảo mật cấp cao nhất, một mảng trống có thể được sử dụng.

servers

[Server Object]

Mỗi giá trị “server” được thay thế cho tên duy nhất một server thật của Operation. Nếu một giá trị “server” bị thay thế thì nó sẽ bị ghi đè nếu được cấp phép bởi quyền cao nhất từ Operation.

16. Đối tượng Reference

Đối tượng Reference là Một đối tượng đơn giản để cho phép tham chiếu các thành phần khác trong đặc tả, bên trong và bên ngoài.

Đối tượng Tham chiếu được định nghĩa bởi tham chiếu JSON và tuân theo cùng một cấu trúc, hành vi và quy tắc.

Đối với đặc điểm kỹ thuật này, độ phân giải tham chiếu được thực hiện như được xác định theo đặc tả Reference JSON chứ không phải bởi đặc tả Schema JSON.

Trường cố định của đối tượng là

Trường

Kiểu data

Miêu tả

$ref

string

Là trường dữ liệu bắt buộc.

Đây là đối tượng không được mở rộng hay bổ sung, mọi thông tin, thuộc tính bổ sung sẽ bị bỏ qua.

Hình 6: ví dụ về đối tượng tham chiếu

17. Đối tượng schema

Đối tượng Schema cho phép định nghĩa các kiểu dữ liệu đầu vào và đầu ra. Những kiểu này có thể là đối tượng, nhưng cũng có thể là nguyên thủy và mảng. Đối tượng này là một tập con mở rộng của Đặc tả lược đồ JSON Wright Draft 00 .

Để biết thêm thông tin về các thuộc tính, hãy xem JSON Schema CoreJSON Schema Validation . Trừ khi được nêu khác đi, các định nghĩa thuộc tính tuân theo Schema JSON.

Tính chất của đối tượng có các thuộc tính sau được lấy trực tiếp từ định nghĩa của tài liệu Schema JSON và tuân theo các thông số kỹ thuật tương tự: title, multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum, maxLength, minLength, pattern, maxItems, minItems, uniqueItems, maxPropertis, minPropertis, required, enum

Các thuộc tính tiếp theo sẽ lấy trực tiếp từ định nghĩa của tài liệu Schema JSON nhưng chúng được điều chỉnh theo đặc tả OAS.

- type: Giá trị này phải là string. Nhưng loại giá trị thông qua mảng thì không được chấp nhận.

- allOf: Là một lượng đồ được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

- oneOf: Là một lượng đồ được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

- anyOf: Là một lượng đồ được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

- not: Là một lượng đồ được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

 - items: giá trị này phải là một đối tượng và không phải là một mảng. Một lượng đồ được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

- properties: các định nghĩa phải được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

- additionalProperties: giá trị này có thể là Boolean hoặc một đối tượng cụ thể. Là một lượng đồ được tham chiếu phải thuộc đối tượng Schema và không phải là Schema JSON.

- description: Cú pháp CommonMark có thể được sử udjng để biểu diễn văn bản đa phương tiện.

- format: xem Data Type Formats để biết chi tiết. Các định dạng khác được xác định theo lượn đồ OAS hay JSON.

- default: là giá trị mặc định nếu người dùng không điền thông tin gì hay không cung cấp thông tin. Không giống như Lược đồ JSON, giá trị phải phù hợp với kiểu được xác định cho đối tượng schema được xác định ở cùng cấp. Ví dụ, nếu “type” là string, thì “default” có thể được "foo" nhưng không thể để là 1.

Kết thúc 2 phần, bài viết đã chia sẻ những khái niệm cơ bản nhất đến đi sâu vào các thành phần cấu thành quan trọng để xây dựng API dựa trên tiêu chuẩn OAS. Đây là cơ sở chia sẻ một cái nhìn tổng quan mà ngắn gọn cho người đọc về các khía cạnh của tiêu chuẩn OAS. Ngày nay, việc xây dựng và phát tiển API đã trở thành chìa khóa của công nghệ, từ đó hướng tới những giá trị cốt lỗi hơn các sản phẩm mà người sử dụng là trung tâm. Đây là tiêu chuẩn mở nhưng yếu tố uy tín đã được công nhận và được chứng minh là cơ sở cho các nhà phát triển, lập trình viên dựa vào đó làm căn cứ xuyên suốt quá trình xây dựng, phát triển ứng dụng sản phẩm.

Thông qua tiêu chuẩn OpenAPI Specification ver 3.0.3, ta có thêm khía cạnh xây dựng các API của chính phủ thuận tiện hơn cho người dân và doanh nghiệp sử dụng các dịch vụ hay chia sẻ kết nối thông tin.

Vũ Cao Minh Đức

Tài liệu tham khảo

- OpenAPI Specification ver 3.0.3 – swagger.io, February 2020.

- YAML Ain’t Markup Language (YAML™) Version 1.2, 3rd Edition, October 2019.

- JSON Schema: A Media Type for Describing JSON Documents draft-wright-json-schema-00, October 13th, 2016, A. Wright, Ed.

239 Go top

Sự kiện nổi bật

Ý kiến về Trang thông tin điện tử Cục Tin học hóa?
1. Đạt yêu cầu, 1180 phiếu (88 %)
2. Chưa đạt yêu cầu, 107 phiếu (8 %)
3. Cần thêm chủ đề, 57 phiếu (4 %)
Tổng số phiếu: 1344
THÔNG KÊ TRUY CẬP
  • Người trực tuyến Người trực tuyến
    • Khách Khách 55
    • Thành viên Thành viên 0
    • Tổng Tổng 55
    • Tổng lượt truy cập: Tổng lượt truy cập: 16558451