title: rspec_api_documentation - How to have multiple examples
body: <p>My goal is to show multiple examples of parameters and responses using rspec_api_documentation with rswag-ui or by adding swagger-ui directly to the project.  I'm having some trouble generating the correct open_api.json with my config and am wondering what I am doing wrong.</p>
  
  <p>Gems: </p>
  
  <ul>
  <li><a href="https://github.com/zipmark/rspec_api_documentation" rel="nofollow noreferrer">https://github.com/zipmark/rspec_api_documentation</a></li>
  <li><a href="https://github.com/rswag/rswag" rel="nofollow noreferrer">https://github.com/rswag/rswag</a></li>
  </ul>
  
  <p>rspec_api_documentation config for tests:</p>
  
  <pre><code># spec/acceptance_helper.rb
  require 'spec_helper'
  require 'rspec_api_documentation'
  require 'rspec_api_documentation/dsl'
  
  RspecApiDocumentation.configure do |config|
    config.app = Rails.application
  
    config.api_name = 'My API'
    config.api_explanation = 'API Description'
  
    config.configurations_dir = Rails.root.join('public', 'docs', 'api', 'config')
    config.docs_dir = Rails.root.join('public', 'docs', 'api', 'generated')
  
    config.format = :open_api
  
    API_VERSIONS.each do |version|
      config.define_group(version) do |config|
        config.docs_dir = Rails.root.join('public', 'docs', 'api', 'generated', version.to_s)
      end
    end
  
    config.client_method = :client
  
    config.io_docs_protocol = 'https'
  
    config.request_headers_to_include = nil
    config.request_body_formatter = :json
  
    config.response_headers_to_include = []
    config.response_body_formatter = Proc.new { |response_content_type, response_body|
      response_body
    }
  end
  
  </code></pre>
  
  <p>OpenAPI config:</p>
  
  <pre><code>swagger: '2.0'
  info:
    title: My Api
    description: Blah.
    termsOfService: 'http://open-api.io/terms/'
    contact:
      name: API Support
      url: 'http://www.open-api.io/support'
      email: support@domain.com
    license:
      name: Apache 2.0
      url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
    version: 1.0.0
  host: 'localhost:3000'
  schemes:
    - http
    - https
  consumes:
    - application/json
  produces:
    - application/json
  
  </code></pre>
  
  <p>Example tests:</p>
  
  <pre><code>require 'documentation_helper'
  
  resource 'Sessions' do
    header 'Accept', 'application/json'
    header 'Content-Type', 'application/json'
  
    explanation 'Endpoints to start and end API sessions for a user'
  
    route '/api/v1/users/sign_in', 'Sign In' do
      route_summary 'Starts a new session for a user'
      route_description 'Given valid credentials, will create a new API session for a user'
  
      post 'Signing in a user', document: :v1  do
        let(:user) { FactoryBot.create(:user) }
  
        parameter :login, 'The username or email of the user', scope: :user, required: true
        parameter :password, 'The password for the user', scope: :user, required: true
  
        example '401 - No user object', document: :v1 do
          request = { login: user.email, password: user.password }
  
          do_request(request)
  
          expect(status).to eq(401)
          expect(json.keys.size).to eq(1)
          expect(json['error']).to eq(I18n.t('devise.failure.unauthenticated'))
        end
  
        example '401 - No login', document: :v1 do
          request = { user: { password: user.password } }
  
          do_request(request)
  
          expect(status).to eq(401)
          expect(json.keys.size).to eq(1)
          expect(json['error']).to eq(I18n.t('devise.failure.unauthenticated'))
        end
      end
    end
  end
  
  </code></pre>
  
  <p>Generated output:</p>
  
  <pre><code>{
    "swagger": "2.0",
    "info": {
      "title": "My Api",
      "description": "Blah.",
      "termsOfService": "http://open-api.io/terms/",
      "contact": {
        "name": "API Support",
        "url": "http://www.open-api.io/support",
        "email": "support@domain.com"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
      },
      "version": "1.0.0"
    },
    "host": "localhost:3000",
    "schemes": [
      "http",
      "https"
    ],
    "consumes": [
      "application/json"
    ],
    "produces": [
      "application/json"
    ],
    "paths": {
      "/api/v1/users/sign_in": {
        "post": {
          "tags": [
            "Sessions"
          ],
          "summary": "Starts a new session for a user",
          "description": "Given valid credentials, will create a new API session for a user",
          "consumes": [
            "application/json"
          ],
          "produces": [
            "application/json"
          ],
          "parameters": [
            {
              "name": "body",
              "in": "body",
              "description": "",
              "required": false,
              "schema": {
                "type": "object",
                "properties": {
                  "user": {
                    "type": "object",
                    "properties": {
                      "login": {
                        "type": "string",
                        "description": "The username or email of the user"
                      },
                      "password": {
                        "type": "string",
                        "description": "The password for the user"
                      }
                    },
                    "required": [
                      "login",
                      "password"
                    ]
                  }
                }
              }
            }
          ],
          "responses": {
            "401": {
              "description": "No login",
              "schema": {
                "type": "object",
                "properties": {
                }
              },
              "headers": {
              },
              "examples": {
                "application/json": {
                  "error": "You need to sign in or sign up before continuing."
                }
              }
            }
          },
          "deprecated": false,
          "security": [
  
          ]
        }
      }
    },
    "tags": [
      {
        "name": "Sessions",
        "description": "Endpoints to start and end API sessions for a user"
      }
    ]
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/NS9sB.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/NS9sB.png" alt="enter image description here"></a>
  Desired output (at least I think):</p>
  
  <pre><code>{
    "swagger": "2.0",
    "info": {
      "title": "My Api",
      "description": "Blah.",
      "termsOfService": "http://open-api.io/terms/",
      "contact": {
        "name": "API Support",
        "url": "http://www.open-api.io/support",
        "email": "support@domain.com"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
      },
      "version": "1.0.0"
    },
    "host": "localhost:3000",
    "schemes": [
      "http",
      "https"
    ],
    "consumes": [
      "application/json"
    ],
    "produces": [
      "application/json"
    ],
    "paths": {
      "/api/v1/users/sign_in": {
        "post": {
          "tags": [
            "Sessions"
          ],
          "summary": "Starts a new session for a user",
          "description": "Given valid credentials, will create a new API session for a user",
          "consumes": [
            "application/json"
          ],
          "produces": [
            "application/json"
          ],
          "parameters": [
            {
              "name": "body",
              "in": "body",
              "description": "",
              "required": false,
              "schema": {
                "type": "object",
                "properties": {
                  "user": {
                    "type": "object",
                    "properties": {
                      "login": {
                        "type": "string",
                        "description": "The username or email of the user"
                      },
                      "password": {
                        "type": "string",
                        "description": "The password for the user"
                      }
                    },
                    "required": [
                      "login",
                      "password"
                    ]
                  }
                }
              }
            }
          ],
          "responses": {
            "401": {
              "description": "Invalid params",
              "schema": {
                "type": "object",
                "properties": {
                }
              },
              "headers": {
              },
              "examples": {
                "No password": {
                  "error": "You need to sign in or sign up before continuing."
                },
                "No login": {
                  "error": "You need to sign in or sign up before continuing."
                }
              }
            }
          },
          "deprecated": false,
          "security": [
  
          ]
        }
      }
    },
    "tags": [
      {
        "name": "Sessions",
        "description": "Endpoints to start and end API sessions for a user"
      }
    ]
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/WiCVo.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/WiCVo.png" alt="enter image description here"></a></p>