Swagger API Doc

Việc tạo một ứng dụng api rails là một điều đơn giản mà hầu hết những người lập trình rails đều đã trải qua. Tuy nhiên việc viết api là một chuyện việc để khác hàng đối tác hay người đọc sử dụng api tin rằng ứng dụng api vẫn chạy tốt là một vấn đề khác , để ứng dụng api được rành mạch tránh việc kiểm thử lại nhiều lần ta cần viết document cho ứng dụng của mình . Rails Swagger đã hỗ trợ việc này !

1. Add thêm dòng sau vào gemfile:

gem 'rswag'

1. Chạy lệnh sau để cài đặt

rails g rswag:install

1. Tạo một spec tích hợp để mô tả và kiểm tra API của bạn.

# spec/integration/blogs_spec.rb
require 'swagger_helper'

describe 'Blogs API' do

  path '/blogs' do

    post 'Creates a blog' do
      tags 'Blogs'
      consumes 'application/json', 'application/xml'
      parameter name: :blog, in: :body, schema: {
        type: :object,
        properties: {
          title: { type: :string },
          content: { type: :string }
        },
        required: [ 'title', 'content' ]
      }

      response '201', 'blog created' do
        let(:blog) { { title: 'foo', content: 'bar' } }
        run_test!
      end

      response '422', 'invalid request' do
        let(:blog) { { title: 'foo' } }
        run_test!
      end
    end
  end

  path '/blogs/{id}' do

    get 'Retrieves a blog' do
      tags 'Blogs'
      produces 'application/json', 'application/xml'
      parameter name: :id, :in => :path, :type => :string

      response '200', 'blog found' do
        schema type: :object,
          properties: {
            id: { type: :integer },
            title: { type: :string },
            content: { type: :string }
          },
          required: [ 'id', 'title', 'content' ]

        let(:id) { Blog.create(title: 'foo', content: 'bar').id }
        run_test!
      end

      response '404', 'blog not found' do
        let(:id) { 'invalid' }
        run_test!
      end

      response '406', 'unsupported accept header' do
        let(:'Accept') { 'application/foo' }
        run_test!
      end
    end
  end
end

1. Tạo file Swagger JSON file(s) bằng lệnh

rake rswag:specs:swaggerize

1. Kiểm tra Để kiểm tra api của mình bạn có thể vào đường dẫn : http://localhost:3000/api-docs

Swagger cung cấp cho bạn một ui để mô tả cho api của bạn. Ngoài ra nó cũng cung cấp và hỗ trợ cho bạn viết spec

1. Nếu bạn muốn thêm sự xác nhận của response trả về , bạn có thể viết vào khối run_test!

response '201', 'blog created' do
run_test! do |response|
  data = JSON.parse(response.body)
  expect(data['title']).to eq('foo')
end
end

1. Nếu như bạn muốn kiểm tra rõ ràng hơn bạn có thể thay thế run_test! tương đương với "before" and "it"

response '201', 'blog created' do
let(:blog) { { title: 'foo', content: 'bar' } }

before do |example|
  submit_request(example.metadata)
end

it 'returns a valid 201 response' do |example|
  assert_response_matches_metadata(example.metadata)
end
end

Null value

Swagger sử dụng thư viện JSON::Draft4 để xác nhận các mô hình phản hồi , nhưng nó ko hỗ trợ value :null, tuy nhiên bạn có thể sử dụng "x-nullable" để khai báo giá trị

describe 'Blogs API' do
path '/blogs' do
  post 'Creates a blog' do
    ...

    response '200', 'blog found' do
      schema type: :object,
        properties: {
          id: { type: :integer },
          title: { type: :string },
          content: { type: :string, 'x-nullable': true }
        }
      ....
    end
  end
end
end

Việc sử dụng swagger sẽ khiến cho api của bạn trở nên dễ hiểu và sử dụng hơn, giảm thiểu các lỗi xảy ra . Hỗ trợ việc viết docs và spec cho api . Tạo ứng dụng chuyên nghiệp . Thank for reading !