Swagger - Công cụ hiệu quả để viết documents cho APIs
Làm gì để viết documents cho APIs xịn hơn
APIs (Application Programming Interfaces) đã từ rất lâu và hiện đang ngày càng phổ biến trong lĩnh vực IT, như dùng APIs vào việc tích hợp các hệ thống và/hoặc các ứng dụng để chúng có thể “trò chuyện” với nhau, cho đến việc xây dựng cung cấp APIs cho đối tác, khách hàng để cung cấp dịch vụ truy vấn dữ liệu hay tài nguyên được cho phép,…
Vì tính phổ biến của APIs nên trong các hoạt động tương tác với APIs chắc chắn không thể thiếu đi documents mô tả cấu hình và hướng dẫn sử dụng chúng được biên soạn bởi các nhà phát triển/nhà cung cấp APIs để giúp cho bên sử dụng có thể hiểu và sử dụng được.
Thông thường, sẽ thấy các bên trao đổi tài liệu về API bằng cách truyền thống như là cung cấp dạng file PDF, Word, Excel,… Bên cạnh đó, cũng có một cách khác để tài liệu API theo hướng “số hóa” hơn và cũng thuận tiện hơn trong việc cập nhật nội dung mô tả đặc tính và hướng dẫn sử dụng các APIs.
Đặc biệt là khi có nhu cầu sử dụng một số lượng lớn APIs (>= 20 APIs chẳng hạn) thì việc lưu các documents dạng files truyền thống có thể hơi phiền toái bởi vì:
Số lượng files documents tương ứng của các APIs mà end-users cần lưu trữ, theo dõi, cập nhật phiên bản cũng tăng dần lên;
Có khả năng bị out of date khi nhà cung cấp dịch vụ APIs đã có cập nhật phiên bản nội dung APIs từ phía họ nhưng phía end-users không được biết cho đến khi bugs xảy ra lúc call APIs hoặc được nhà cung cấp APIs thông báo;
Việc scroll 1 file API document định dạng pdf/docx dài 20 pages để tìm đến chỗ cần tìm kiếm cũng cho trải nghiệm đậm đà “kiên nhẫn” hơn, rối mắt hơn kể cả khi bạn dùng chức năng tìm kiếm Command+F (MacOS)/Ctrl + F (Windows) để “bay” nhanh đến điểm tìm kiếm đó.
Swagger là một tool khá nổi tiếng để ứng dụng vào việc số hóa tài liệu APIs
Tưởng tượng có 30 Clients subscribed đang gọi vào API “abc” để request/response có trả phí mỗi ngày, khi API “abc” có cập nhật nội dung về mô tả cấu hình khai báo hoặc cách sử dụng API có thay đổi từ phía nhà cung cấp dịch vụ API chẳng hạn. Lúc đó nhà cung cấp dịch vụ API phải gửi files document phiên bản mới nhất đến từng 30 Clients. Thậm chí kể cả khi gửi files dạng đính kèm link download thì Clients cũng cần phải quản trị lưu trữ lịch sử các versions của tài liệu và vẫn phải đọc file theo kiểu PDF/Word/Excel.
Trong khi nếu sử dụng Swagger, host nó lên một server (Ví dụ URL: https://swagger.api.documents/apiabc) và publish cho 30 Clients vậy là xong, chỉ cần thông báo đến các Clients và họ tự truy cập URL ở trên để xem nội dung cập nhật của API “abc” với một giao diện thân thiện hơn và không cần phải quản trị lưu trữ tài liệu
…và nhìn bá hơn!
Theo Sách Giáo Khoa:
Swagger là một bộ công cụ mã nguồn mở để xây dựng OpenAPI specifications giúp bạn có thể thiết kế, xây dựng tài liệu và sử dụng REST APIs
Swagger cung cấp các services SwaggerHub, Swagger Editor, Swagger UI, Swagger Codegen.
Trong khuôn khổ bài viết này, mình sẽ chia sẻ về viết docs APIs bằng Swagger UI.
Với Swagger UI chúng ta sẽ biên tập APIs docs trên file định dạng *.yaml (swagger.yaml). Cấu trúc file yaml này có thể tham khảo tại https://editor.swagger.io/
https://editor.swagger.io/
Là trình Editor mô phỏng kết quả giao diện tương ứng khi khai báo trong swagger.yaml giúp người dùng thuận tiện hơn khi biên soạn APIs docs mà không cần phải restart/refresh lại service Swagger UI đã deploy trước đó.
Và vì trên mạng cũng rất nhiều nguồn viết về Swagger nên mình không nêu chi tiết thêm, các bạn có thể search Google tìm hiểu chi tiết về các thành phần khai báo trong file *.yaml, mình thấy trang này mô tả cũng được nè click tại đây
Để hình dung trước giao diện của Swagger UI sau khi deploy nó có hình dạng như thế nào, các bạn có thể tham khảo tại https://petstore.swagger.io/
OK! Vô chuyện. Vậy triển khai Swagger UI như thế nào ?
Cài đặt Swagger UI từ source code download từ trang chủ của Swagger, tại đây
Cài đặt Swagger UI bằng Docker
—> Mình chọn thực hiện theo cách này, lý do vì…thích và việc xây dựng các services (không chỉ Swagger) bằng docker mình thấy cũng rất tiện lợi trong khâu deployment, cũng như gọn gàng trong việc quản lý, vận hành nhờ vào việc các services đã được đóng gói từ các images có sẵn, mình chỉ cần pull về rồi custom lại theo đúng nhu cầu sử dụng và không yêu cầu quá nhiều trong việc setup và config môi trường.
Triển khai Swagger UI bằng Docker
BƯỚC 1: Pull docker image Swagger
Trên terminal, các bạn run command:
docker pull swaggerapi/swagger-uiBƯỚC 2: Chuẩn bị file swagger.yaml
Chuẩn bị trước file swagger.yaml lưu ở local.
Tên mặc định của file là “swagger.yaml”, nhưng chúng ta có thể đặt lại bằng một cái tên mà mình mong muốn, ví dụ ở đây mình đặt là “swagger-99percent.yaml”
Để thuận tiện và dễ dàng hơn ở bước đầu, các bạn nên copy full template swagger.yaml tại trình Editor của Swagger https://editor.swagger.io/ và chưa cần chỉnh sửa gì. Lưu lại file swagger.yaml này ở một folder trên local, folder này sẽ dùng để mount với thư mục chứa file swagger.yaml thuộc docker container khi khởi tạo.
Ví dụ, mình sẽ lưu tại đường dẫn: ../mySwagger/swagger-ui/dist/swagger-99percent.yaml
BƯỚC 3: Khởi tạo container chạy dịch vụ Swagger UI
Khởi tạo container chạy service Swagger UI, command:
docker run -it --name c-swagger-1 -p 80:8080 -v ../mySwagger/swagger-ui/dist/swagger-99percent.yaml:/swagger.yaml -e SWAGGER_JSON=/swagger.yaml swaggerapi/swagger-uiDiễn giải:
Trỏ tới đường dẫn chứa file swagger-99percent.yaml vừa tạo ở BƯỚC 2 và mount/map nó với file /swagger.yaml chứa trong container.
Port mặc định container swagger là 8080 --> ánh xạ về port 80 của host (local) đang run container này.
Ok! Press Enter and…GO!!!
BƯỚC 4: Vào giao diện Swagger UI
Trên trình duyệt web, các bạn đi đến URL http://localhost:80
Chúng ta được giao diện được render từ nội dung file swagger-99percent.yaml như này
Note: Nội dung file swagger-99percent.yaml hiện tại là copy từ full template từ trang Editor của Swagger
BƯỚC 5: Modify nội dung file swagger-99percent.yaml
Chúng ta tiến hành biên tập lại nội dung file này theo mong muốn.
Mình biên tập lại như bên dưới (scroll down xem ở cuối bước này)
và refresh lại trình duyệt URL http://localhost:80
TADA !!!
Mô tả các parameters cần khai báo đầu vào khi gửi API request
Mô tả các output khi nhận API responses (Code 200 và Code 403)
File: ../mySwagger/swagger-ui/dist/swagger-99percent.yaml
# swagger-99percent.yaml
swagger: "2.0"
info:
description: "99 Percent API Documentation"
version: "1.0.0"
title: "99Percent API"
#termsOfService: "http://swagger.io/terms/"
contact:
email: "never100percent@abc.com"
#license:
# name: "Apache 2.0"
# url: "http://www.apache.org/licenses/LICENSE-2.0.html"
schemes:
- http
host: 172.116.11.11
basePath: "/api/v1"
tags:
- name: "99-percent"
description: "Tags description: Never 100 Percent Version 1.0"
paths:
/ninetyninepercent:
post:
tags:
- "API Description"
summary: "Đây là đường dẫn paths /ninetyninepercent"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/json"
- "application/xml"
parameters:
- in: "body"
name: "Request Body"
description: "description_API_Key"
schema:
type: "object"
required:
- key
- live_data
properties:
key:
type: "object"
required:
- api_key
properties:
api_key:
type: "string"
example: "111111-222222-333333-444444-555555-666666"
input_data:
type: "object"
required:
- customer_id
- store_id
- city
- product_id
properties:
customer_id:
type: "integer"
example: "123456"
store_id:
type: "integer"
example: "789101112"
city:
type: "string"
example: "Hue City"
product_id:
type: "string"
example: "123456789111"
responses:
200:
description: "Get Info success"
schema:
type: "object"
properties:
requested_by:
type: "string"
example: "partner_A"
requested_params:
type: "object"
required:
- customer_id
- store_id
- product_id
- city
properties:
customer_id:
type: "integer"
example: "123456"
store_id:
type: "integer"
example: "789101112"
city:
type: "string"
example: "Hue City"
product_id:
type: "string"
example: "123456789111"
requested_ts:
type: "string"
example: "2024-06-10 10:35:123.456"
responsed_message:
type: "object"
required:
- customer_id
- rating
- responsed_code
properties:
customer_id:
type: "integer"
example: "123456"
rating:
type: "string"
example: "5 Stars"
responsed_code:
type: "integer"
example: 200
responsed_ts:
type: "string"
example: "2024-06-10 10:36:123.456"
403:
description: "Invalid API Key"
schema:
type: "object"
properties:
requested_by:
type: "string"
example: "Unknown"
requested_params:
type: "string"
example: ""
requested_ts:
type: "string"
example: "2024-06-10 10:36:123.456"
responsed_message:
type: "object"
required:
- message
- responsed_code
properties:
message:
type: "string"
example: "The provided API key is not valid"
reponsed_code:
type: "integer"
example: 403KẾT
Trên đây mình vừa giới thiệu về ứng dụng Swagger vào việc viết tài liệu cho APIs, tất nhiên vẫn còn một vài trò vọc vạch hơn nữa từ Swagger UI các bạn có thể tìm hiểu thêm, mình chỉ nêu ra các phần chính để có thể sử dụng nó.
Với việc ứng dụng Swagger UI, mình thấy khá tiện lợi, đặc biệt khi cần quản lý danh mục hàng tá các nguồn dữ liệu được publish bằng APIs cho các bên/ứng dụng khác kết nối sử dụng.
Việc cập nhật nội dung APIs được nhanh chóng hơn, nhìn cũng chuyên nghiệp và có hệ thống hơn. Phía end-users cũng theo dõi được ngay các nội dung đã được cập nhật trong khi nhà cung cấp dịch vụ APIs không cần phải export files riêng lẻ để gửi cho từng end-users nữa.
Và cuối cùng, chúng ta hoàn toàn có thể deploy Swagger lên một server bất kỳ nào theo cách ở trên.
Cảm ơn quý bạn đọc.
Nếu có góp ý vui lòng để lại comment ở phần bình luận.
Writer: Gia Nguyễn
thanks for sharing this <3