Gem apipie

Hi all,

Rails một phần phổ biến cũng bởi 1 điều rằng những những dev mobile thường ít có khả năng dev server cho mình, với lợi thế dễ học mà lại vừa chuyên nghiệp nên các dev mobile thường hay chọn Rails để phát triển phần back-end (server) của bản thân.

Đó là việc của các dev mobile, còn những bạn dev Ruby on Rails khi được khách hàng yêu cầu api cho ứng dụng của họ thì bạn thường viết document cho api như thế nào?

Với apipie-rails đã làm thay đổi cách viết document, cùng nhìn hình bên dưới để xem sau khi sử dụng apipie-rails sẽ có giao diện như thế nào nhé?

Các ưu điểm là:

• Dễ dàng chỉnh sửa, document luôn được cập nhật (vì khi deploy dự án sẽ cũng thay đổi luôn doc).
• Chạy ngay trên domain của bạn, cùng với ứng dụng Rails.
• Nhìn rất chuyên nghiệp vì dùng modun doc của Rails
• Nhìn rất trực quan, không mất nhiều thời gian với việc phải dùng Google Driver, phải gen PDF. 😀

Sau đây cùng tìm hiểu cách cài đặt và các bước để viết api document nhé.

B1: Add gem

gem 'apipie-rails'

Sau đó bundle install bạn nhé.

Tiếp theo ta sẽ chạy lệnh sau để gen ra các file cấu hình.

rails g apipie:install

Lúc này bạn xem trong folder config sẽ thấy file apipie.rb.

B2: CẤU HÌNH

Đây là một mẫu file mình dùng cho dự án bạn có thể tham khảo qua:

Apipie.configure do |config|
  config.app_name                = "AAAAAAAAAAAAAAAAAAA"
  config.app_info = "This is document for app AAAAAAAAAAAAAAA."
  config.copyright = "&copy"
  config.api_base_url            = "/api/v1/" # đây sẽ là url cơ bản cho các api bạn viết.
  config.doc_base_url            = "/api/doc" # Đường dẫn để vào xem document api
  # where is your API defined? # Nơi chứa các file api bạn xây dựng. 
  config.api_controllers_matcher = "#{Rails.root}/app/controllers/api/v1/*.rb"
 # Bên dưới là config để sử dụng simple authentication.
  config.authenticate = Proc.new do
     authenticate_or_request_with_http_basic do |username, password|
       username == "xxxxxxxxxxxxxx" && password == "yyyyyyyyyyyyyyyyy"
    end
  end
end

Muốn biết thêm các config bạn có thể thao khảo tại github của gem

B3: VIẾT API DOCUMENT.

Trong mỗi API Controller bạn thêm như sau để define cho 1 resource api

resource_description do
    short 'This is API for REG DEVICE INFO FOR DO SOME THING BLA BLA'
    formats ['json']
    description <<-EOF
      == Required
     MUST BE INCLUDED IN HEADER OF EACH REQUEST:
      SOME THING YOU WANT TO DESCRIPTION
    EOF
  end

Trưóc mỗi action bạn thêm như nội dung như sau:

*** Chú ý method dùng cho api này là :POST tùy mỗi api của bạn có thể là :GET/:POST/:PUT/:DELETE/:PATCH Sau method sẽ là đường dẫn, bạn còn nhớ base url trên config không, nếu mình viết như thế thì gem này tự hiểu đường dẫn sẽ là domain/api/v1/vote, nhớ điều này nhé bạn.***

api :POST, 'vote', 'Đây là nội dung hiển thị' description "Miêu tả cho api này, tùy bạn"
 # errors code if have any
 # Bắt đầu với từ khóa error để chỉ rằng các lỗi sẽ có thể xảy ra trong api này và miêu tả của nó. 
error code: 404, :desc => "Not Found" 
error code: 996, desc: "Missing params to create vote for this book" 
error code: 303, desc: "Exsiting in system"
 error code: 996, desc: "Create fail"
 # params 
# Từ khóa bắt đầu với param nghĩa là các biến truyền lên server có cấu trúc  như sau
# param :biến, Kiểu dữ liệu (String, Integer, Hash, ...), desc: "Miêu tả", required: true/false (nghĩa là có bắt buộc hay không)
# Để có thể tìm thêm về cách bắt các param bạn có thể xem thêm tại github của gem như mình đã nói.
# Ở đây mình viết bắt param dưới dạng params nested.
param :vote, Hash, desc: 'vote', required: true do
   param :book_id, String, :desc => "Book id for vote", :required => true 
   param :device_id, String, :desc => "Id of Device vote", :required => true 
end 
# return data example
# Bắt đầu với từ khóa example để chỉ định đây là các kết quả trả về mẫu
# Cấu trúc là example 'Dữ liệu trả về'
 example ' { "success": true, "vote": { "id": 1, "book_id": 2, "created_at": "2017-07-27T08:01:51.479Z", "updated_at": "2017-07-27T08:01:51.479Z" } } ' 
example ' { "success": false, "error": { "code": 303, "message": "Your device was vote for this book" } } '

Mong rằng bạn sẽ có 1 cách làm document mới cho phần API của dự án.