Create API Doc với gem APIPIE

Document là thứ rất quan trọng có thể nói là bắt buộc khi bàn giao một dự án hay cần tham khảo để bảo trì, phát triển dự án đó. Hiện nay những ứng dụng theo mô hình restfull api đang thực sự phát triển, nhưng có rất nhiều dự án lại không có một tài liệu rõ ràng để bên mobile và server có thể giao tiếp được với nhau một cách thuận tiện nhất. Những developer thiếu kinh nghiệm vì lý do đặc thù công việc thường không coi trọng việc viết Docs cho API vì lý do ngại hoặc nghĩ rằng chỉ cần đọc code là đủ. Thường thường với những dự án trước đây chúng ta thường sử dụng Excel để đặc tả API của mình, tuy vậy việc này khá mất thời gian về giao diện, không đầy đủ và khó khăn trong việc cập nhật. Vậy làm thế nào để giảm thiểu thời gian viết DOCS cho API, tạo dựng và chỉnh sửa nó một cách thuận tiện nhất? Gem apipie-rails là một công cụ viết DOCS cho API trên Framework Ruby on Rails một cách hiệu quả, nó không yêu cầu người lập trình phải học thêm một ngôn ngữ mới hay đau đầu phải thiết kế style cho dễ hiểu, việc cập nhật và chỉnh sửa nó cũng thật sự dễ ràng.

• 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.

Cài đặt ứng dụng Rails 5 với API

rails new viblo_11 --api -T

Việc này sẽ tạo một project Rails với những config đặc thù cho API các bạn có thể đọc thêm tại đây

Create bảng User

class CreateUsers < ActiveRecord::Migration[5.1]
  def change
    create_table :users do |t|

      t.string :name
      t.integer :age
      t.string :email
      t.timestamps
    end
  end
end

Thêm gem apipie-rails

gem "apipie-rails"

Run bundle install

Cài đặt config cho gem

rails g apipie:install

Gem apipie-rails sẽ tự tạo các config cần thiết cho mình.

FRAMGIAphan.thanh.giang@framgia0216-lt:~/Jobs/viblo_11$ rails g apipie:install
Running via Spring preloader in process 4594
/usr/share/rvm/gems/ruby-2.4.1/gems/spring-2.0.2/lib/spring/application.rb:185: warning: Insecure world writable dir /usr/share/rvm/gems in PATH, mode 042777
      create  config/initializers/apipie.rb
       route  apipie

• config/initializers/apipie.rb: File này sẽ chứa những config cơ bản của gem như:

Apipie.configure do |config|
  #name của project
  config.app_name                = "Viblo11"
  # Router mặc định khi chạy api
  config.api_base_url            = "/api"
  #Router của file docs
  config.doc_base_url            = "/apipie"
  # Ngôn ngữ được sử dụng trên docs
  config.languages                = ["en", "ja"]
  # where is your API defined?
  config.api_controllers_matcher = "#{Rails.root}/app/controllers/**/*.rb"
end

• route apipie: Config routes mặc định của gem

Khởi tạo API user action show như sau URL: /api/v1/users

class Api::V1::UsersController < ApplicationController
  include ::Users::Show

  def show
    user = User.find_by id: params[:id]
    if user.present?
      render json: {
        success: true,
        data: {
          users: user.as_json}
      }
    else
      render json: {success: false, 
        errors: {error_code: 3001,
          message: "Couldn't find User with 'id'=#{params[:id]}"}}
    end
  end
end

Như chúng ta đã thấy API này có include file include ::Users::Show đây chính là file docs của API này.

Create file docs demo cho API này như sau File docs sẽ được khởi tạo trong folders docs có đường dẫn như sau app/docs/

module Users::Show
  extend Apipie::DSL::Concern

  api :GET, "/v1/users/:id", "Detail of user"

  meta author: {name: "Thanh Giang"}

  error 3001, "record not found"

  example <<-EOS
    - Request
    ■ URL: /api/v1/users/1
    ■ Method : GET
    Header:
      Authorization : yes

    - Response
    ■ Status : 200
    ■ Body :
    {
      "success": true,
      "data": {
        "users": {
          "id": 1,
          "name": "Thanhgiang",
          "age": 26,
          "email": "giang.phan1106@gmail.com",
          "created_at": "2017-11-26T06:48:53.325Z",
          "updated_at": "2017-11-26T06:48:53.325Z"
        }
      }
    }

    - Request
    ■ URL: /api/v1/users/1000
    ■ Method : POST
    Header:
      Authorization : yes

    - Response
    ■ Status : 200
    ■ Body :
    {
      "success": false,
      "errors": {
        "error_code": 3001,
        "message": "Couldn't find User with 'id'=1000"
      }
    }
  EOS

  def show
  end
end

Trên đây là một file demo cho một doc của API chúng ta sẽ từ từ giải thích từng option một.

1. extend Apipie::DSL::Concern

Là module của apipie-rails chứa các khai báo #api, #error, #param, #error. Tất cả docs của API đều phải kế thừa từ DSL này. 2. api :GET, "/v1/users/:id", "Detail of user"

Khai báo method của API, đường dẫn URL của API tương ứng, mô tả của API.

1. meta author: {name: "Thanh Giang"}

Tên của người viết Docs này. 4. example <<-EOS

Example json của kết quả trả về. 5. def show

Action của API thường lấy theo controller.

Kết quả

Khi chạy từ project với đường dẫn http://localhost:3000/apipie/1.0/users/show.en.html sẽ có kết quả như sau.

Như chúng ta đã thấy, việc khởi tạo Docs cho API thật dễ ràng và tiện lợi phải không?, bài viết của mình chỉ hướng dẫn cơ bản nhất để có thể tạo một Docs cơ bản cho API các bạn có thể tìm hiểu thêm về các tính năng của apipie-rails ở đây

Thanks you for reading !!!