Một số tip & tricks khi sử dụng apipie để viết document cho rails

Apipie là một gem raasrt hay nó hỗ trợ viết document cho RESTful API.

Một số ưu điểm của gem này là :

• Viết document như code bằng Ruby =))
• Quản lý document và Reusing dễ dàng.
• Có thể gộp chung cùng source code để quản lý bằng git.

Cách sử dụng bạn có thể tham khảo: https://github.com/Apipie/apipie-rails Ở đây mình chỉ giới thiệu 1 số tip & tricks khi dùng apipie.

Cấu trúc folders Trong hướng dẫn trên github, document được viết luôn trong controller. Nhưng như thế controller phình to ra, khó quản lý, rối mắt. Khi review thì document và code không tách bạch nhau ra Cách giải quyết là đặt toàn bộ document trong thư mục app/docs và mình sẽ include vào:

# app/controllers/lists_controller.rb
  class ListsController < ActionController::Base
    include ListsDoc
    ...
    end

ListsDoc trong app/docs/lists_doc.rb

# app/docs/lists_doc.rb
module ListsDoc
  extend Apipie::DSL::Concern

  api :GET, '/lists/:id', '(Done) Get lists'
  param :id, :number, required: true
  param :page, :number
  param :limit, :number
  error :code => 401, :desc => "Unauthorized"
  error :code => 404, :desc => "Not Found"
  def show
  end
    …
end

Như vậy sẽ làm code trong controller đẹp hơn.

Show db schema Trong rails có file db/schema.rb để define các table. File này được cập nhật mỗi khi chạy migration, vì thế nó luôn đảm bảo là DB mới nhất.

Giờ ta sẽ đọc file này và show lên document :

module DbDoc
  extend Apipie::DSL::Concern
  api :GET, '/db/', 'DB schema.'
  description "DB schema."
  example <<-EXAMPLE
  #{File.read('db/schema.rb') if File.exist?('db/schema.rb')}
  EXAMPLE
  def db_schema
  end
end

Tạo resource là common Thường thường thì sẽ tạo thêm 1 resource là common để cho các document khác vào đây. Ví dụ như :

• Authentication
• DB schema …

Phải sửa document và cho vào PR 1 quy ước nhỏ để đảm bảo document luôn được làm cẩn thận và cập nhật. Thêm 1 label need document, sau khi review và code đã sẵn sàng merge sẽ dùng label này để update document mới nhất lên.

Trên đây là 1 số tip&trick trong quá trình sử dụng Apipie mình ngộ ra, hy vọng giúp ích cho các bạn