前提
rswagの公式Docを見ながらAPI仕様書の自動作成に取り組んでいた時の話。
自動作成までの手順として、RSpecでAPIのテストを書いた後、ターミナルでRAILS_ENV=test rake rswag:specs:swaggerizeを実行する。
すると、swagger/v1/swagger.yaml が自動で作成されて、api-docs/index.html にアクセスするとswaggerのAPIDocが確認できる。
うまく行ったこと
createアクションはドキュメント通りに以下のようなテストを作った。（ユーザーに関するAPI）
users_spec.rb
require 'swagger_helper'
RSpec.describe 'api/v1/users', type: :request do
path '/api/v1/users' do
post('create user') do
# リクエストボディがJSON形式であることを示す
consumes 'application/json'
parameter name: :user, in: :body, schema: {
type: :object,
properties: {
name: { type: :string },
email: { type: :string },
password: { type: :string }
},
required: [:name, :email, :password]
}
response '201', 'user created' do
let(:user) { { name: 'test_user', email: 'test@example.com', password: 'test_pass' } }
run_test!
end
response '422', 'パスワード無しでリクエスト' do
let(:user) { { name: 'test_user', email: 'test@example.com' } }
run_test!
end
end
end
end
RAILS_ENV=test rake rswag:specs:swaggerizeを実行すると、
swgger.yamlが作成された。
swagger.yaml
---
openapi: 3.0.1
info:
title: API V1
version: v1
paths:
"/api/v1/users":
post:
summary: create user
parameters: []
responses:
'201':
description: user created
'422':
description: パスワード無しでリクエスト
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
password:
type: string
required:
- name
- email
- password
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: localhost:3000
api-docs/index.html にアクセスしてみると、ちゃんとプロパティも反映された状態で確認できた。
困ったこと
indexアクションのテストの書き方の参考が公式Docにはありませんでした。自分流に書いたのですが、上画像のプロパティ欄がなかなか表示されませんでした。
僕に公式Docを読み解く力があれば解決できたかもしれないのですが。。。まだまだ苦手です。
一人で試行錯誤しました。
解決策
海外で同じことで苦しんだ人がいました。バージョンダウンするだけでした、何じゃそりゃ、、、
Just replace opeanapi: '3.0.1' for swagger: '2.0'. I've faced this same issue and this is the only workaround I've found so far.
swagger_helper.rb
RSpec.configure do |config|
config.openapi_root = Rails.root.join('swagger').to_s
config.openapi_specs = {
'v1/swagger.yaml' => {
swagger: '2.0',
info: {
title: 'API V1',
version: 'v1'
},
paths: {},
servers: [
{
url: 'https://{defaultHost}',
variables: {
defaultHost: {
default: 'localhost:3000'
}
}
}
]
}
}