Chắc hẳn khi làm việc với API, việc xây dựng tài liệu (documents) đặc tả API, chức năng, tham số, các respone là điều cần thiết. Nếu như bạn đang gặp khó khăn trong việc đặt tả này hay không muốn đặc tả trên các file định dạng excel chưa theo chuẩn thì hãy xem xét sử dụng Swagger.

Swagger cho phép bạn đặc tả cấu trúc APIs của bạn để máy có thể đọc được. Khả năng mô tả API đến tận “root” là điều thật tuyệt vời mà Swagger mang lại.

Swagger không chỉ đặc tả cấu trúc APIs, nó còn làm được nhiều hơn thế với hệ sinh thái đa dạng như sinh tạo 1 stub server cho APIs, sinh thư viện clients với 40 ngôn ngữ hay việc có thể test API trên chính Swagger. Tuy nhiên trọng phạm vi bài viết, mình chỉ nói về cấu trúc file mà Swagger sử dụng để đặc tả API.

Demo:

• Swagger API
• Swagger demo with editor

1. Basic Structure

Swagger có thể được viết dưới dạng JSON hoặc YAML. Trong hướng dẫn này, chúng tôi chỉ sử dụng ví dụ dạng YAML nhưng JSON hoạt động tốt tương đương. Một Swagger với định dạng YAML sẽ có dạng như sau

Nào, chúng ta cùng điểm qua các thành phần của nó là cái gì nhé

2. Metadata

Khởi đầu cho mỗi Swagger bắt đầu với version, 2.0 đang là phiên bản cuối cùng của nó. Phiên bản giúp các trình dịch hiểu được cấu trúc tổng thể của phần nội dung tiếp theo.

Tiếp theo, bạn cần định nghĩa các thông tin về API trong trường info với các trường title, description (tùy chọn), version (API version, không phải version của file hay Swagger)

3. Base URL

Base URL là phần dùng cho tất cả các API định nghĩa bao gồm: schemes, host, basePath:

Tất cả các đường link API đều quan hệ với base URL này. Ví dụ /users thực tế có nghĩa là https://api.example.com/v1/users.

4. Consumes, Produces

Phần Consumes và produces định nghĩa loại MIME được hỗ trợ bởi API. “Root-level” định nghĩa có thể được ghi đè bởi các toán tử riêng biệt (các API cụ thể có thể định nghĩa lại phần này).

5. Path

Phần này chính là phần quan trọng, định nghĩa từng API cụ thể và phương thức HTTP được hỗ trợ trong các API này. GET /users được mô tả như sau:

6. Parameters

Các toán tử có thể cần các tham số dựa trên URL path (/users/{userId}), query string (/users?role=admin), headers (X-CustomHeader: Value)và trong request body. Bạn có thể định nghĩa các loại tham số, cấu trúc, mô tả chi tiết, yêu cầu hay tùy chọn hoặc các thông tin khác trong swagger như sau:

7. Responses

Mỗi API tất nhiên đều response về một trạng thái (status codes) như 200 OK hoặc 404 Not Found và schema (cấu trúc) của response body. Schemas này thì có thể được định nghĩa trực tiếp trong respone hoặc có thể tách ra định nghĩa ngoài vùng dựa bào $ref

8. Input and Output Models

Phần definitions sẽ định nghĩa các cấu trúc dữ liệu chung để sử dụng trong API của bạn. Phần này có thể được tham chiếu qua $ref bất cứ một shema nào – ở cả request body và response body. Ví dụ đây là JSON object:

Có thể được mô tả bởi

Và được tham chiếu trong request body schema và response body schema như sau thông qua $ref:

9. Authentication

Từ khóa securityDefinitions và security được sử dụng để mô tả các phương thức yêu cầu xác thực.

Phương thức xác thức được hỗ trợ bao gồm:

• Basic authentication
• API key (as a header or query parameter)
• OAuth 2 common flows (implicit, password, application and access code)

Tài liệu tham khảo

• Swagger Editor
• Basic Strcuture