OAS là gì?
OAS (OpenAPI Specification) là chuẩn mở để mô tả các RESTful API dưới dạng máy có thể đọc được. Nó cho phép bạn định nghĩa toàn bộ API—các endpoint, tham số, schema dữ liệu, phương thức xác thực—trong một tài liệu JSON hoặc YAML duy nhất. Chuẩn này giúp API providers và API consumers giao tiếp hiệu quả mà không cần truy cập mã nguồn hay kiểm tra lưu lượng mạng.
Vai trò của OAS trong tích hợp hệ thống
OAS là nền tảng cho toàn bộ vòng đời của API. Nó cung cấp một “tạo tác đầu ra” rõ ràng và có thể kiểm soát phiên bản từ quá trình thiết kế API, sau đó được sử dụng để phát triển, tạo tài liệu tự động, sinh mã client, và tạo các trường hợp kiểm thử. Với OAS, các công cụ tự động hóa có thể khám phá cách API hoạt động, hiểu được khả năng của dịch vụ, và tạo client code mà không cần can thiệp thủ công.
Trong bối cảnh automation và workflow, OAS giúp các hệ thống tự động tích hợp và trao đổi dữ liệu một cách đáng tin cậy bằng cách cung cấp định nghĩa rõ ràng về cách gọi API, định dạng dữ liệu mong đợi, và các phản hồi có thể xảy ra.
OAS được sử dụng như thế nào trong thực tế?
Một tài liệu OpenAPI (gọi là OpenAPI Description) bao gồm các thành phần chính:
- Paths – danh sách các endpoint API (ví dụ
/pets) và các phương thức HTTP được hỗ trợ - Parameters – các tham số query, path, header, hoặc body mà API chấp nhận
- Responses – các phản hồi có thể xảy ra từ mỗi endpoint, bao gồm HTTP status code và định dạng dữ liệu
- Components/Schemas – các schema dữ liệu tái sử dụng (ví dụ
Pets,Error,Invoice) được định nghĩa một lần và tham chiếu trong toàn bộ tài liệu bằng$ref
Ví dụ, một endpoint được mô tả trong OAS có thể trông như thế này:
“`yaml paths: /pets: get: summary: List all pets parameters:
- name: limit
in: query schema: type: integer responses: ‘200’: description: A paged array of pets content: application/json: schema: $ref: “#/components/schemas/Pets” “`
Các công cụ như Swagger UI, Redoc, và các client SDK generators đọc tài liệu OAS này để tự động tạo ra tài liệu API tương tác, client libraries, và test cases. Trong automation workflows, OAS cho phép các node hoặc ứng dụng tự động hiểu được API nào có sẵn, cách gọi chúng, và cách xử lý kết quả mà không cần hard-code thông tin chi tiết.
Những lưu ý quan trọng về OAS
OAS hỗ trợ cả dữ liệu nhị phân thô (raw binary) lẫn dữ liệu nhị phân được mã hóa (encoded binary). Khi dữ liệu nhị phân được nhúng trong định dạng chỉ text như application/json, nó phải được mã hóa (thường là base64).
Các schema được định nghĩa trong Components Object không có tác dụng trên API trừ khi chúng được tham chiếu rõ ràng từ bên ngoài. Điều này giúp tài liệu OAS vẫn sạch sẽ và dễ bảo trì.
OAS hiện hỗ trợ cả tài liệu đơn (một file JSON/YAML) và tài liệu phân tán (nhiều file được kết nối bằng $ref). Một phiên bản mở rộng gọi là Arazzo cho phép mô tả các quy trình API multi-step—một chuỗi các lệnh gọi API mà mỗi bước tham chiếu tài liệu OpenAPI hiện có.
Các thuật ngữ liên quan đến OAS
Các thuật ngữ sau có liên quan chặt chẽ với OpenAPI Specification:
- OpenAPI Description (OAD): tài liệu hoàn chỉnh mô tả bề mặt và ngữ nghĩa của một API, có thể bao gồm nhiều tệp được kết nối bằng tham chiếu.
- JSON Schema: định dạng để mô tả cấu trúc dữ liệu JSON, được sử dụng rộng rãi trong các phần schema của OAS để định nghĩa request body và response structure.
- REST API: giao diện API dựa trên HTTP protocol mà OAS được thiết kế để mô tả và chuẩn hóa.
- Swagger: tên cũ của OpenAPI Specification, hiện nay Swagger là tên của bộ công cụ và framework do SmartBear phát triển để làm việc với OpenAPI documents.
Các câu hỏi thường gặp
OAS khác gì với Swagger?
OAS là chuẩn specification, Swagger là tên của bộ công cụ (Swagger UI, Swagger Editor, v.v.) được sử dụng để làm việc với OAS. Trước đây, chuẩn này gọi là Swagger Specification, nhưng đã được đổi tên thành OpenAPI Specification để phản ánh rằng nó là một chuẩn mở, không chỉ riêng của SmartBear.
Tôi có thể dùng OAS để tự động sinh mã client không?
Có, đây là một trong những lợi ích chính của OAS. Các công cụ như OpenAPI Generator có thể đọc tài liệu OAS và tự động tạo client libraries cho nhiều ngôn ngữ lập trình (Python, JavaScript, Java, v.v.) mà không cần viết thủ công.
OAS có hỗ trợ API không phải REST không?
OpenAPI Specification được thiết kế chủ yếu cho REST APIs và HTTP-based services. Tuy nhiên, các chuẩn khác như AsyncAPI được tạo ra để mô tả APIs không đồng bộ và event-driven systems.
Tôi nên sử dụng JSON hay YAML cho tài liệu OAS?
Cả hai đều hợp lệ; YAML dễ đọc hơn cho con người, JSON dễ phân tích bằng máy. Phần lớn mọi người chọn YAML để viết tài liệu OAS, nhưng công cụ thường hỗ trợ cả hai định dạng.