I didn't find any examples of how to use rswag to generate documentation according to json api.
spec/integration/pets_spec.rb
require 'swagger_helper'
It is possible to change the code to generate the format of json api?
describe 'Pets API' do
path '/api/v1/pets' do
post 'Creates a pet' do
tags 'Pets'
consumes 'application/json', 'application/xml'
parameter name: :pet, in: :body, schema: {
type: :object,
properties: {
name: { type: :string },
photo_url: { type: :string },
status: { type: :string }
},
required: [ 'name', 'status' ]
}
response '201', 'pet created' do
let(:pet) { { name: 'Dodo', status: 'available' } }
run_test!
end
response '422', 'invalid request' do
let(:pet) { { name: 'foo' } }
run_test!
end
end
end
path '/api/v1/pets/{id}' do
get 'Retrieves a pet' do
tags 'Pets'
produces 'application/json', 'application/xml'
parameter name: :id, :in => :path, :type => :string
response '200', 'name found' do
schema type: :object,
properties: {
id: { type: :integer, },
name: { type: :string },
photo_url: { type: :string },
status: { type: :string }
},
required: [ 'id', 'name', 'status' ]
let(:id) { Pet.create(name: 'foo', status: 'bar', photo_url: 'http://example.com/avatar.jpg').id }
run_test!
end
response '404', 'pet not found' do
let(:id) { 'invalid' }
run_test!
end
end
end
end
If rswag what tips would you give me?
You need to change the swagger_helper.rb file. Change the file format to JSON. I have attached the screenshot for that one below:
https://i.stack.imgur.com/MzOR9.png
Related
I have spent a lot of time trying to emplement ability of validation incoming params is rswag specs, my code:
# incoming-parameter
params = {
login: 'www',
id: 15
}
# test rswag-spec
path '/controller/hello' do
post('Say Hello!') do
tags 'users'
consumes 'application/json'
produces 'application/json'
parameter name: :my_params, in: :body, schema: {
type: :object,
required: %i[id name],
properties: {
id: { type: :string },
name: { type: :string }
}
}
response(200, 'successful') do
# schema '$ref' => '#/components/schemas/UserRegistrationResponse'
describe 'new user with valid reg_params' do
let(:my_params) { params }
run_test! do |response|
data = JSON.parse(response.body)
puts "data = #{data}"
end
end
end
end
end
You expecting that incoming params won't pass validation, because id - is an integer, and name field is absent. But that's doesn't matter and test is compliting with success.
Can you say what's wrong with my code an why don't work validation of incoming parameters those declarated in rswag docs?
I'm getting this error when I run the rspec
Response body: {"success":false,"errors":["Invalid login credentials"]}
here is my code
path '/api/auth/validate_token' do
get 'check token' do
tags 'TokenValidations'
consumes 'application/json'
security [client: {}, uid: {}, access_token: {}]
response '200', 'success' do
let(:headers) { user.create_new_auth_token }
run_test!
end
end
end
Thanks in advance
I think I had the same problem and tried to execute below, then worked for me.
let(:user) { FactoryBot.create(:user, password: 'password') }
let(:tokens) do
post "/api/v1/authority/sign_in",
params: { email: user[:email], password: 'password' },
as: :json
response.headers.slice('client', 'access-token', 'uid')
end
path '/api/v1/messages/' do
get 'Retrieves some messages' do
description 'Get some messages from provided data'
produces 'application/json'
parameter name: 'access-token', in: :header, type: :string
parameter name: 'client', in: :header, type: :string
parameter name: 'uid', in: :header, type: :string
response '200', 'messages found' do
let(:client) { tokens['client'] }
let('access-token') { tokens['access-token'] }
let(:uid) { tokens['uid'] }
schema '$ref' => '#/components/schemas/messages'
run_test!
end
end
end
I have some common parameters which are called in almost all API calls so is it possible to create component for those parameters and call them in rswag api request.
Something like schema '$ref' => '#/definitions/parameters'
Thanks!
Add in your swagger_helper.rb
Example:
# spec/swagger_helper.rb
config.swagger_docs = {
'v1/swagger.json' => {
swagger: '2.0',
info: {
title: 'API V1'
},
definitions: {
errors_object: {
type: 'object',
properties: {
errors: { '$ref' => '#/definitions/errors_map' }
}
},
errors_map: {
type: 'object',
additionalProperties: {
type: 'array',
items: { type: 'string' }
}
}
}
}
}
# spec/integration/blogs_spec.rb
describe 'Blogs API' do
path '/blogs' do
post 'Creates a blog' do
response 422, 'invalid request' do
schema '$ref' => '#/definitions/errors_object'
...
end
# spec/integration/comments_spec.rb
describe 'Blogs API' do
path '/blogs/{blog_id}/comments' do
post 'Creates a comment' do
response 422, 'invalid request' do
schema '$ref' => '#/definitions/errors_object'
...
end
From: https://www.rubydoc.info/github/domaindrivendev/rswag#referenced-parameters-and-schema-definitions
You need to define your object in spec/swagger_helper.rb
Then in integration spec file define
path '/api/client/v0/blog' do
put 'Create a blog' do
tags :Blog
include_examples 'header_with_recognition_definitions'
parameter name: :input_param, in: :body, schema: { '$ref' => '#/definitions/input_parameter_object' }
response 200, 'blog was created successfully' do
include_examples 'header_with_recognition_lets'
...
run_test!
end
end
How do I add a custom parameter in my rswag-specification?
Rswag seems to consumate only parameters which exists as fields
but I need to add a custom parameter. So whatever I do - I can see in controllers params only fields of my model.
RSpec.describe Api::V1::LogsController, type: :request do
path '/api/v1/logs' do
post 'Create a Log' do
tags 'Logs'
security [ApiKeyAuth: {}]
consumes 'application/json'
produces 'application/json'
parameter name: :log, in: :body, schema: {
type: :object,
properties: {
title: { type: :string },
description: { type: :string },
my_custom_parameter: { type: :string }
},
required: %w(title description user_phone_number),
}
response '200', 'New Log created' do
let(:Authorization) { "Token token=#{company.api_key}" }
run_test!
end
end
end
end
you can add any parameters with any name that you liked,
and then you can give values to those parameters in the response block like below:
parameter name: :params, in: :body, schema: {
type: :object,
properties: {
profile_attributes: {
type: :object,
properties: {
email: { type: :string, example: Faker::Internet.email(Faker::Name.first_name) }
},
required: %w[email]
}
response('201', 'successfully') do
let(:params) do
{
profile_attributes: { email: Faker::Internet.email(Faker::Name.first_name) }
}
end
Here is my API post:
resource :service_requests do
get do
authenticate!
current_company.service_requests
end
params do
requires :service_request, type: Hash do
optional :prefix, type: String
requires :first_name, type: String
requires :last_name, type: String
requires :contact_email, type: String, regexp: User::EMAIL_REGEX
requires :telephone, type: String
end
end
post do
authenticate!
{ service_request: params[:service_request] }
end
end
Here is what my json post looks like:
{
'service_request': {
'first_name': 'Foo',
'last_name': 'Bar',
'contact_email': 'foo#bar.com',
'telephone': '111-111-1111'
}
}
The error I am receiving is:
ActionDispatch::ParamsParser::ParseError (795: unexpected token at '{
'service_request': {
'first_name': 'Foo',
'last_name': 'Bar',
'contact_email': 'foo#bar.com',
'telephone': '111-111-1111'
}
}'):
Not sure what I am doing wrong. Anyone see anything that stands out?
Use double quotes in your json:
{
"service_request": {
"first_name": "Foo",
"last_name": "Bar",
"contact_email": "foo#bar.com",
"telephone": "111-111-1111"
}
}