Rswag - Tạo API documents

I. Giới thiệu

• Rswag là công cụ cho Rails API. Tạo các tài liệu API đẹp, bao gồm UI để kiểm tra các hoạt động trực tiếp từ các kiểm tra tích hợp rspec của bạn.
• Rswag là mở rộng của rspec-rails dựa vào Swagger-based DSL để mô tả và thử nghiệm các API
• Bạn mô tả các hoạt động API của mình bằng cú pháp trực quan, ngắn gọn và tự động chạy các bài test. Khi bạn đã chạy qua được tất cả các bài test, chạy rake taskđể tự động tạo các tập tin Swagger tương ứng dưới dạng các điểm cuối JSON. Rswag cũng cung cấp một phiên bản nhúng cho phép đọc từ JSON tạo ra UI cho người dùng. Công cụ này làm cho nó liền mạch có thể tích hợp cùng spec, mà từ đó bạn có thể làm tài liệu cho người dùng API của bạn.

1. Bắt đầu

• Add vào Gemfile

  gem "rswag"
  

• Chạy lệnh cài đặt và khởi tạo rails g rswag:install
• Tạo 1 api để test:

    def create
      user = User.new user_params
      if user.save
        render json: user, serializier: UserSerializer, status: 201
      else
        render json: { errors: user.errors }, status: 422
      end
    end
    
    private
    def user_params
      params.permit User::USER_PARAMS
    end
  

• Ta viết spec cho api trên
  • Rswag chỉ đọc được khi mình viết spec vào spec/api hoặc spec/integration
  • spec/api/v1/users_api_spec.rb

  require "swagger_helper"
  
  describe "User API" do
    path "/api/v1/sign_up" do
      post "User sign_up" do
        consumes "application/json", "application/xml"
  
        parameter name: :params, in: :body, schema: {
          type: :object,
          properties: {
            email: { type: :string },
            password: { type: :password },
            name: { type: :string },
            nickname: { type: :string }
          },
          required: %i(email password),
          example: {
            email: "example@gmail.com",
            password: "your_password",
            name: "dummy_name",
            nickname: "dummy_nickname"
          }
        }
  
        response "201", "User created" do
          let(:params) do
            {
              email: "example@gmail.com",
              password: "12345678",
              name: "dummy_name",
              nickname: "dummy_nickname"
            }
          end
  
          schema "$ref" => "#/definitions/user"
  
          examples "application/json" => {
              id: 1,
              email: "example1@gmail.com",
              name: "dummy_name",
              nickname: "dummy_nickname",
              created_at: Time.now,
              updated_at: Time.now
          }
  
          run_test!
        end
      end
    end
  end
  

  • Một số thuộc tính

  path "/api/v1/sign_up" do
    post "User sign_up" do
    ......
    end
  end
  

  path là endpoint của api post là method của api User sign_up là mô tả

   parameter name: :params, in: :body, schema: {
    type: :object,
    properties: {
      email: { type: :string },
      password: { type: :password },
      name: { type: :string },
      nickname: { type: :string }
    },
    required: %i(email password),
    example: {
      email: "example@gmail.com",
      password: "your_password",
      name: "dummy_name",
      nickname: "dummy_nickname"
    }
  }
  

  Ta định nghĩa các params của api, những trường nào cần required Tạo example để dựa vào đó người sử dụng api biết cần có những trường nào và format chuẩn

  response "201", "User created" do
    let(:params) do
      {
        email: "example@gmail.com",
        password: "12345678",
        name: "dummy_name",
        nickname: "dummy_nickname"
      }
    end
  
    schema "$ref" => "#/definitions/user"
  
    examples "application/json" => {
        id: 1,
        email: "example1@gmail.com",
        name: "dummy_name",
        nickname: "dummy_nickname",
        created_at: Time.now,
        updated_at: Time.now
    }
  
    run_test!
  end
  

  Khởi tạo params, examples để người dùng biết format của JSON trả về
• Chạy lệnh để tạo Swagger JSON rake rswag:specs:swaggerize
• UI sẽ được hiển thị khi mình tạo xong Swagger JSON

  #config/routes.rb
  mount Rswag::Ui::Engine => "/api-docs"
  mount Rswag::Api::Engine => "/api-docs"