ruby-on-railsrubyswaggerrswag

Using rswag in Rails - what is the syntax for index responses (arrays)?


Unfortunately the "documentation" for rswag seems pretty lacking and doesn't give an example of how to implement an index action. My "create" spec displays the Schema and Example Value in the Swagger UI, but my "index" method isn't displaying either of those in the UI.

What do I need to change here? I've played around with it based on the limited examples I've found and none of them seem to work.

path '/api/v1/users' do

get('list users') do
  tags 'Users'

  response(200, 'successful') do
    schema type: :array,
           properties: {
             id: { type: :integer },
             title: { type: :string },
             created_at: { type: :datetime},
             updated_at: { type: :datetime}
           }
    after do |example|
      example.metadata[:response][:content] = {
        'application/json' => {
          example: JSON.parse(response.body, symbolize_names: true)
        }
      }
    end
    run_test!
  end
end

post('create user') do
  tags 'Users'
  consumes 'application/json'
  parameter name: :user, in: :body, schema: {
    type: :object,
    properties: {
      title: { type: :string }
    },
  required: [ 'title', 'description' ]
}
  response(200, 'successful') do

    after do |example|
      example.metadata[:response][:content] = {
        'application/json' => {
          example: JSON.parse(response.body, symbolize_names: true)
        }
      }
    end
    run_test!
  end
end
end

I have also tried to format the schema like so, based on another example I found, which didn't do anything either (schema/example just aren't displaying):-

    schema type: :object,
           properties: {
             collection: {
               type: :array,
               items: {
                 type: :object,
                 properties: {
                   id: { type: :integer },
                   title: { type: :string },
                   created_at: { type: :datetime},
                   updated_at: { type: :datetime}
                 }
               }
             }
           }

Solution

  • Check your swagger_helper file. If you've followed the documentation, it's probably something like that:

    RSpec.configure do |config|
      config.swagger_root = Rails.root.to_s + '/swagger'
    
      config.swagger_docs = {
        'v1/swagger.json' => {
          openapi: '3.0.1',
          info: {
            title: 'API V1',
            version: 'v1',
            description: 'This is the first version of my API'
          },
          servers: [
            {
              url: 'https://{defaultHost}',
              variables: {
                defaultHost: {
                    default: 'www.example.com'
                }
              }
            }
          ]
        }
      }
    end
    

    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.