Swagger API Doc
This post hasn't been updated for 3 years
Giới thiệu
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 !
Cài đặt
- Add thêm dòng sau vào gemfile:
gem 'rswag'
- Chạy lệnh sau để cài đặt
rails g rswag:install
- 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
- Tạo file Swagger JSON file(s) bằng lệnh
rake rswag:specs:swaggerize
- 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
Rspec
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
- 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
- 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
Kết luận
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 !
All Rights Reserved