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: "[email protected]",
              password: "your_password",
              name: "dummy_name",
              nickname: "dummy_nickname"
            }
          }
    
          response "201", "User created" do
            let(:params) do
              {
                email: "[email protected]",
                password: "12345678",
                name: "dummy_name",
                nickname: "dummy_nickname"
              }
            end
    
            schema "$ref" => "#/definitions/user"
    
            examples "application/json" => {
                id: 1,
                email: "[email protected]",
                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
    
    pathendpoint của api postmethod 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: "[email protected]",
        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: "[email protected]",
          password: "12345678",
          name: "dummy_name",
          nickname: "dummy_nickname"
        }
      end
    
      schema "$ref" => "#/definitions/user"
    
      examples "application/json" => {
          id: 1,
          email: "[email protected]",
          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"
    

All Rights Reserved