Rails API’s documentation with Swagger

Bài viết này giả định bạn đã có kiến thức cơ bản về Web API with rails and grape gem, nếu chưa, vui lòng đọc bài viết của mình trước khi đi tiếp 🙂
Bài viết cũng được viết dựa trên source code của bài viết kia.
Chân thành cảm ơn anh @NhutVD – Ruby lead – AsianTech inc. đã hỗ trợ mình hoàn thành bài viết này

Tình huống

Khi viết Web service cho một dự án, bạn phải viết documentation (hay API cho gọn) cho service này để những lập trình viên khác (client, front-end) tương tác với service của mình. Thường, chúng ta sẽ chọn giải pháp viết thông tin vào một file xong xuất ra pdf và gửi cho các lập trình viên khác. Hoặc viết lên một trang Google doc rồi share link.

Vấn đề

  1. Khi bạn đã bàn giao file API cho client dev, bạn muốn sửa một vài phương thức, sửa vài tham số…Bạn phải sửa file và gửi bản cập nhật cho client dev.
  2. Nhóm của bạn muốn làm việc song song, tức là client dev sẽ sử dụng phương thức của bạn ngay khi bạn viết nó xong. Vấn đề này có thể giải quyết bằng Google doc. Nhưng:
  3. client dev sẽ phải đọc thông tin trong file của bạn, xong sang một trình rest client (Postman chẳng hạn), điền thông tin theo như bạn yêu cầu, và thực hiện gọi thử API.
    Swagger là giải pháp cho tất cả những vấn đề trên: tạm biệt ác mộng viết documentation, tạm biệt ác mộng copy/paste từng trường để test API.

Swagger

Swagger là một công cụ giúp ta sinh documentation một cách tự động, song song với quá trình bạn viết code service.
Với swagger, bạn không phải viết documentation nữa, bạn không phải cần Postman trợ giúp nữa, bạn không còn phải copy/paste từng trường nữa. Tất cả gói gọn trong một và được sinh gần như tự động.
Nhìn hình dưới:

Tích hợp vào rails web service

Cài đặt cấu hình

Routes:

Gemfile:

Cập nhật Gemfile:

Vào thư mục config/initializers/ tạo file swagger.rb với nội dung:

Vào core_api.rb, thêm nội dung sau:

Tích hợp

Post

Kết quả:
post

Get

Kết quả:
get

Request header

Kết quả:
header

Default api-token

Nếu bạn muốn sử dụng một api-token xuyên suốt trong tất cả các lời gọi API, thêm vào swagger.rb nội dung:

Thì tham số api_token sẽ được nối vào link(http://localhost:3000/v1/lesson.json?api_token=secret token) và bạn có thể truy cập bằng request.params:

Chạy thử

Truy cập http://localhost:3000/swagger và tận hưởng thành quả.

Source code:

Toàn bộ mã nguồn của dự án bạn có thể xem tại:

Source code on git hub

Source code on git hub swagger branch

Hoặc bạn có thể clone trực tiếp unit-test branch bằng lệnh sau:

Lập trình và hơn thế nữa

Spread the love
  •  
  •  
  •  
  •  
  •  

Leave a Reply

1 Comment on "Rails API’s documentation with Swagger"

avatar
  Subscribe  
newest oldest most voted
Notify of
trackback

[…] Bài này là bài đầu tiên trong loạt ba bài viết về vấn đề làm rails web service, các bài khác bạn có thể xem tại: 1. Web API with rails and grape gem 2. Unit test for grape on rails with airborne framework 3. Rails API’s documentation with Swagger […]