Tài liệu hướng dẫn sử dụng API là một nội dung kỹ thuật, nó chứa tất cả các thông tin được yêu cầu để có thể làm việc với API, với thông tin chi tiết về các tài nguyên, phương thức, các request và response, thông tin chứng thực, … được hỗ trợ bởi các hướng dẫn và ví dụ.
Tại sao tài liệu hướng API lại quan trọng?
- Sản phẩm của chúng ta có thể là tốt nhất, nhưng sẽ không có ai sử dụng nó nếu họ không biết nó làm gì và sử dụng như thế nào.
- Cải thiện trải nghiệm người dùng: nếu bạn có tài liệu hướng dẫn tốt, nhiều người sẽ dễ dàng tìm thấy giá trị trong các dịch vụ của bạn và sử dụng chúng.
- Giúp nhiều người biết đến API của bạn: khi có nhiều người chấp nhận và sử dụng các API của chúng ta, họ sẽ giúp chúng ta giới thiệu về các sản phẩm tuyệt vời mà họ đã sử dụng.
- Tiết kiệm thời gian hỗ trợ và chi phí: tài liệu hướng dẫn tốt, cũng giảm lượng thời gian phải bỏ ra để hỗ trợ những người dùng mới, các thành viên mới của team hoặc đối tác.
- Dễ bảo trì hơn: giúp team của chúng ta biết các chi tiết của tài nguyên, phương thức, các request và response, giúp cho việc bảo trì và cập nhật nhanh hơn.
Swagger là gì?
Swagger là một bộ công cụ mã nguồn mở để xây dựng OpenAPI specifications giúp chúng ta có thể thiết kế, xây dựng tài liệu và sử dụng REST APIs.
Swagger cung cấp 3 tools chính cho các developers :
- Swagger-Editor : dùng để design lên các APIs hoàn toàn mới hoặc edit lại các APIs có sẵn thông qua 1 file config.
- Swagger-Codegen : dùng để generate ra code từ các file config có sẵn.
- Swagger-UI : dùng để generate ra file html,css,… từ 1 file config.
Việt viết document cho Swagger có hai cách tiếp cận chính như sau:
- Top-down approach: thiết kế các API trước khi code.
- Bottom-up approach: từ các API có sẵn thiết kế file config để mô tả chúng.
Trong các tools trên, Swagger UI được sử dụng nhiều nhất, nó giúp sinh ra giao diện cho tài liệu từ file config dưới chuẩn OpenAPI. Giao diện được hiện ra rõ ràng và tường minh. Dễ dàng đọc hiểu cho cả lập trình viên lẫn người dùng. Sử dụng file config nhưng hoàn toàn tách biệt tác vụ với nhau.
Link demo với Swagger UI: https://petstore.swagger.io/
Tại đây ta có thể biết rõ được các thông tin chi tiết về API như: thông tin dự án, các API được cung cấp, method và url tương ứng của nó:
Với mỗi API chúng ta có thể biết được chi tiết input và output cũng như trường nào bắt buộc gửi lên, kết quả trả về có thể nhận những status nào. Đặc biệt, ta có thể input data để thử kiểm tra kết quả.
Phần tiếp theo sẽ có nội dung về cấu trúc cơ bản về Swagger và cách cài đặt trên server cụ thể theo mô hình Bottom-up approach.
Tài liệu tham khảo:
