Open API được biết đến với tên đầy đủ là Open API Specification. Đây được biết đến là một loại định dạng dùng để mô tả API cho một Rest APIs hiện nay. Với duy nhất một file Open API, bạn sẽ có thể mô tả được toàn bộ API. Điều này có nghĩa là việc mô tả sẽ bao gồm cả những nội dung sau đây:
API specifications có thể được viết bằng YAML hoặc JSON. Định dạng này dễ đọc, dễ hiểu cho cả người dùng lẫn ngôn ngữ máy tính.
Nếu như Open API có ý nghĩa quan trọng như trên thì điều gì đã tạo nên được bộ mô tả này? Và đó chính là Swagger. Swagger được hiểu là một công cụ có mã nguồn mở và dùng để xây dựng nên Open API Specifications. Công cụ này sẽ giúp bạn trong việc thiết kế, tạo dựng các tài liệu cũng như việc sử dụng Rest APIs.
Với các nhà phát triển, khi sử dụng Swagger sẽ được cung cấp 3 tool chính như sau:
Để có thể thực hiện việc viết document cho Swagger thì các developers sẽ có 2 cách để tiếp cận với bộ mã nguồn mở này.
– Cách 1: Top down approach: dùng để thiết kế nên các APIs trước khi thực hiện việc code liên quan.
– Cách 2: Bottom down approach: dùng để mô tả các vấn đề, thông số liên quan API thông qua việc sử dụng thiết kế có sẵn của file config.
Với những tool được liệt kê ở trên của Swagger thì Swagger UI được biết đến là một tool có sự thông dụng phổ biến nhất hiện nay. Với tool Swagger UI, tool này có ứng dụng rất lớn trong việc xây dựng giao diện cho các tài liệu bắt nguồn từ file config áp dụng dưới chuẩn của Ipen API. Giao diện được tạo ra bởi tool này thường có tính tường minh và khá rõ ràng, hiện ra một cách cụ thể nhất cho các nhà phát triển. Điều này sẽ giúp ích rất lớn cho cả người dùng lẫn các lập trình viên trong việc đọc hiểu và sử dụng. Thêm vào đó, đây cũng là dẫn chứng có việc các developers sử dụng file config nhưng lại có sự tách biệt một cách hoàn toàn giữa các tác vụ với nhau.
Mỗi API được sử dụng trong quá trình này sẽ cho chúng ta biết một cách chính xác nhất về nguồn vào và nguồn ra một cách chi tiết. Thêm vào đó chính là việc những trường cần phải được gửi lên hệ thống cũng như các trạng thái kết quả có thể được trả về. Điều đặc biệt nhất có lẽ chính là việc ta có thể đưa các dữ liệu vào trong để test thử các kết quả liệu có thực sự chính xác và đảm bảo tính đúng đắn hay không.
Mỗi OpenAPI specifications sẽ bắt đầu với từ khóa openapi để khai báo phiên bản (VD: openapi: 3.0.0). Phiên bản này sẽ định nghĩa toàn bộ cấu trúc của API Phân info sẽ chứa những thông tin của API như: title, desscription (tùy chọn), version
title là tên API của bạndescription là thông tin mở rộng về API của bạn. Bạn có thể viết thành nhiều dòng & hỗ trợ cú pháp Markdowninfo cũng hỗ trợ những từ khóa về thông tin liên lạc, chứng chỉ, điều khoản sử dụng và những thông tin khácinfo:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
Đây là phần sẽ chỉ định đường dẫn của server để ta có thể test được API. Bạn có thể định nghĩa một hoặc nhiều server
Tất cả đường dẫn API sẽ là đường dẫn tương đối của URL mà bạn định nghĩa. Ảnh bên phải là phần UI sẽ hiển thị ra
Đây là phần trọng tâm của API. Ở phần này bạn sẽ định nghĩa những paths trong API của bạn cũng như phương thức, tham số trong API
paths/user/{userId})GET, POST, DELETE, PUT …)summary là phần mô tả tóm tắt của APIparameters: sẽ là những tham số truyền vào API. Bạn có thể set tham số required hay không, mô tả nó (description) hoặc validate. Đặc biệt trong phần này. bạn có thể chỉ định 1 schema (hiểu nôm na là 1 Model) để có thể định nghĩa cho phần tham số thông qua schema & $refresponse là phần trả về của server. Bạn có thể định nghĩa những HTTP code: 200, 404, 500 … với những mô tả cho từng trường hợpBạn có thể hiểu nôm na đây là 1 Model. Phần này được khai báo qua từ khóa component & schemas (Lưu ý: những chỗ gọi đến schema này phải chỉ định chính xác đường dẫn VD $ref: "#/components/schemas/User" 
User)object)You need to login in order to like this post: click here
YOU MIGHT ALSO LIKE
SUBSCRIBE TO OUR NEWSLETTER
