From 9c297317b2eeb4b4ebaca76c85210fddd56d97f2 Mon Sep 17 00:00:00 2001
From: Oleg Yakovenko <olegykz@gmail.com>
Date: Thu, 4 Jun 2020 16:21:43 +0300
Subject: [PATCH 01/17] keep examples content

---
 README.md                                     | 43 ++++++++++---------
 .../lib/generators/rspec/templates/spec.rb    |  6 ++-
 .../lib/rswag/specs/swagger_formatter.rb      |  4 +-
 3 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index fd3f05c..a0c5024 100644
--- a/README.md
+++ b/README.md
@@ -363,8 +363,8 @@ you should use the folowing syntax, making sure there are no whitespaces at the
 
 ### Specifying/Testing API Security ###
 
-Swagger allows for the specification of different security schemes and their applicability to operations in an API. 
-To leverage this in rswag, you define the schemes globally in _swagger_helper.rb_ and then use the "security" attribute at the operation level to specify which schemes, if any, are applicable to that operation. 
+Swagger allows for the specification of different security schemes and their applicability to operations in an API.
+To leverage this in rswag, you define the schemes globally in _swagger_helper.rb_ and then use the "security" attribute at the operation level to specify which schemes, if any, are applicable to that operation.
 Swagger supports :basic, :bearer, :apiKey and :oauth2 and :openIdConnect scheme types. See [the spec](https://swagger.io/docs/specification/authentication/) for more info, as this underwent major changes between Swagger 2.0 and Open API 3.0
 
 ```ruby
@@ -416,7 +416,7 @@ describe 'Blogs API' do
 end
 
 # example of documenting an endpoint that handles basic auth and api key based security
-describe 'Auth examples API' do 
+describe 'Auth examples API' do
   path '/auth-tests/basic-and-api-key' do
     post 'Authenticates with basic auth and api key' do
       tags 'Auth Tests'
@@ -437,11 +437,11 @@ describe 'Auth examples API' do
     end
   end
 end
- 
+
 
 ```
 
-__NOTE:__ Depending on the scheme types, you'll be required to assign a corresponding parameter value with each example. 
+__NOTE:__ Depending on the scheme types, you'll be required to assign a corresponding parameter value with each example.
 For example, :basic auth is required above and so the :Authorization (header) parameter must be set accordingly
 
 ## Configuration & Customization ##
@@ -479,9 +479,9 @@ rake rswag:specs:swaggerize PATTERN="spec/swagger/**/*_spec.rb"
 
 ### Referenced Parameters and Schema Definitions ###
 
-Swagger allows you to describe JSON structures inline with your operation descriptions OR as referenced globals. 
+Swagger allows you to describe JSON structures inline with your operation descriptions OR as referenced globals.
 For example, you might have a standard response structure for all failed operations.
-Again, this is a structure that changed since swagger 2.0. Notice the new "schemas" section for these. 
+Again, this is a structure that changed since swagger 2.0. Notice the new "schemas" section for these.
 Rather than repeating the schema in every operation spec, you can define it globally and provide a reference to it in each spec:
 
 ```ruby
@@ -549,7 +549,7 @@ end
 
 ### Response headers ###
 
-In Rswag, you could use `header` method inside the response block to specify header objects for this response. 
+In Rswag, you could use `header` method inside the response block to specify header objects for this response.
 Rswag will validate your response headers with those header objects and inject them into the generated swagger file:
 
 ```ruby
@@ -597,16 +597,20 @@ To enable examples generation from responses add callback above run_test! like:
 
 ```
 after do |example|
-  example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) }
+  example.metadata[:response][:content] = {
+    'application/json' => {
+      example: JSON.parse(response.body, symbolize_names: true)
+    }
+  }
 end
 ```
 
 You need to disable --dry-run option for Rspec > 3
 
-<!-- This is now enabled by default in rswag. 
+<!-- This is now enabled by default in rswag.
 You need to set the ``` config.swagger_dry_run = false``` value in the spec/spec_helper.rb file.
 This is one of the more powerful features of rswag. When rswag runs your integration test suite via ```bundle exec rspec```, it will capture the request and response bodies and output those values in the examples section.
-These integration tests are usually written with ```let``` variables for post body parameters, and since its an integration test the service is returning actual values. 
+These integration tests are usually written with ```let``` variables for post body parameters, and since its an integration test the service is returning actual values.
 We might as well re-use these values and embed them into the generated swagger to provide a more real world example for request/response examples. -->
 
 Add to config/environments/test.rb:
@@ -645,8 +649,8 @@ describe 'Blogs API', document: false do
 ```
 
 ##### rswag helper methods #####
-<!-- 
-There are some helper methods to help with documenting request bodies. 
+<!--
+There are some helper methods to help with documenting request bodies.
 ```ruby
 describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
   let(:api_key) { 'fake_key' }
@@ -682,7 +686,7 @@ describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
       end
     end
   end
-end    
+end
 ```
 
 In the above example, we see methods ```request_body_json``` ```request_body_plain``` ```request_body_xml```.
@@ -692,7 +696,7 @@ and the examples: :blog which will create a named example "blog" under the "requ
 Again, documenting request response examples changed in Open API 3.0. The example above would generate a swagger.json snippet that looks like this:
 
 ```json
-        ... 
+        ...
         {"requestBody": {
           "required": true,
           "content": {
@@ -726,9 +730,9 @@ Again, documenting request response examples changed in Open API 3.0. The exampl
         }
 ```
 
-*NOTE:* for this example request body to work in the tests properly, you need to ``let`` a variable named *blog*. 
+*NOTE:* for this example request body to work in the tests properly, you need to ``let`` a variable named *blog*.
 The variable with the matching name (blog in this case) is eval-ed and captured to be placed in the examples section.
-This ```let``` value is used in the integration test to run the test AND captured and injected into the requestBody section. 
+This ```let``` value is used in the integration test to run the test AND captured and injected into the requestBody section.
 
 ##### rswag response examples #####
 
@@ -826,7 +830,7 @@ You can specify custom headers for serving your generated Swagger JSON. For exam
 ```ruby
 Rswag::Api.configure do |c|
   ...
-  
+
   c.swagger_headers = { 'Content-Type' => 'application/json; charset=UTF-8' }
 end
 ```
@@ -898,6 +902,5 @@ docker pull swaggerapi/swagger-editor
 ```
 docker run -d -p 80:8080 swaggerapi/swagger-editor
 ```
-This will run the swagger editor in the docker daemon and can be accessed 
+This will run the swagger editor in the docker daemon and can be accessed
 at ```http://localhost```. From here, you can use the UI to load the generated swagger.json to validate the output.
-
diff --git a/rswag-specs/lib/generators/rspec/templates/spec.rb b/rswag-specs/lib/generators/rspec/templates/spec.rb
index 346e348..de3bac5 100644
--- a/rswag-specs/lib/generators/rspec/templates/spec.rb
+++ b/rswag-specs/lib/generators/rspec/templates/spec.rb
@@ -19,7 +19,11 @@ RSpec.describe '<%= controller_path %>', type: :request do
 <%      end -%>
 
         after do |example|
-          example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) }
+          example.metadata[:response][:content] = {
+            'application/json' => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
         end
         run_test!
       end
diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb
index 0b15f12..2fa7e93 100644
--- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb
+++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb
@@ -129,13 +129,13 @@ module Rswag
       end
 
       def upgrade_content!(mime_list, target_node)
-        target_node.merge!(content: {})
+        target_node[:content] ||= {}
         schema = target_node[:schema]
         return if mime_list.empty? || schema.nil?
 
         mime_list.each do |mime_type|
           # TODO upgrade to have content-type specific schema
-          target_node[:content][mime_type] = { schema: schema }
+          (target_node[:content][mime_type] ||= {}).merge!(schema: schema)
         end
       end
 

From 1ff396fb5612f634de6e8d032fb381e1538cb000 Mon Sep 17 00:00:00 2001
From: Oleg Yakovenko <olegykz@gmail.com>
Date: Thu, 4 Jun 2020 17:17:30 +0300
Subject: [PATCH 02/17] example group helper adjustment

---
 rswag-specs/lib/rswag/specs/example_group_helpers.rb     | 9 ++++++++-
 .../spec/rswag/specs/example_group_helpers_spec.rb       | 9 +++++++--
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/rswag-specs/lib/rswag/specs/example_group_helpers.rb b/rswag-specs/lib/rswag/specs/example_group_helpers.rb
index 591a7e9..6d32a95 100644
--- a/rswag-specs/lib/rswag/specs/example_group_helpers.rb
+++ b/rswag-specs/lib/rswag/specs/example_group_helpers.rb
@@ -72,9 +72,16 @@ module Rswag
       def examples(example = nil)
         return super() if example.nil?
 
-        metadata[:response][:examples] = example
+        metadata[:response][:content] =
+          example.each_with_object({}) do |(mime, example_object), memo|
+            memo[mime] = { example: example_object }
+          end
       end
 
+      # example.metadata[:response][:content] = {
+      #   'application/json' => { example: json }
+      # }
+
       def run_test!(&block)
         # NOTE: rspec 2.x support
         if RSPEC_VERSION < 3
diff --git a/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb b/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb
index 2922523..40bca7b 100644
--- a/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb
+++ b/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb
@@ -137,9 +137,10 @@ module Rswag
       end
 
       describe '#examples(example)' do
+        let(:mime) { 'application/json' }
         let(:json_example) do
           {
-            'application/json' => {
+            mime => {
               foo: 'bar'
             }
           }
@@ -151,7 +152,11 @@ module Rswag
         end
 
         it "adds to the 'response examples' metadata" do
-          expect(api_metadata[:response][:examples]).to eq(json_example)
+          expect(api_metadata[:response][:content]).to match(
+            mime => {
+              example: json_example[mime]
+            }
+          )
         end
       end
     end

From 81c110022ec618ff5dc400ce47a2aa67904f8947 Mon Sep 17 00:00:00 2001
From: Oleg Yakovenko <olegykz@gmail.com>
Date: Thu, 4 Jun 2020 17:19:15 +0300
Subject: [PATCH 03/17] example json actualized

---
 test-app/swagger/v1/swagger.json | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/test-app/swagger/v1/swagger.json b/test-app/swagger/v1/swagger.json
index 957206c..874e8ab 100644
--- a/test-app/swagger/v1/swagger.json
+++ b/test-app/swagger/v1/swagger.json
@@ -235,16 +235,14 @@
                 "type": "string"
               }
             },
-            "examples": {
-              "application/json": {
-                "id": 1,
-                "title": "Hello world!",
-                "content": "Hello world and hello universe. Thank you all very much!!!",
-                "thumbnail": "thumbnail.png"
-              }
-            },
             "content": {
               "application/json": {
+                "example": {
+                  "id": 1,
+                  "title": "Hello world!",
+                  "content": "Hello world and hello universe. Thank you all very much!!!",
+                  "thumbnail": "thumbnail.png"
+                },
                 "schema": {
                   "$ref": "#/definitions/blog"
                 }

From 7c3c35729117ba05ce7cf5966541be52959e601f Mon Sep 17 00:00:00 2001
From: Oleg Yakovenko <olegykz@gmail.com>
Date: Thu, 4 Jun 2020 17:22:20 +0300
Subject: [PATCH 04/17] cleanup

---
 rswag-specs/lib/rswag/specs/example_group_helpers.rb | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/rswag-specs/lib/rswag/specs/example_group_helpers.rb b/rswag-specs/lib/rswag/specs/example_group_helpers.rb
index 6d32a95..2a2cdec 100644
--- a/rswag-specs/lib/rswag/specs/example_group_helpers.rb
+++ b/rswag-specs/lib/rswag/specs/example_group_helpers.rb
@@ -78,10 +78,6 @@ module Rswag
           end
       end
 
-      # example.metadata[:response][:content] = {
-      #   'application/json' => { example: json }
-      # }
-
       def run_test!(&block)
         # NOTE: rspec 2.x support
         if RSPEC_VERSION < 3

From 30002e5b986d7386f9dbd2c1701f63cffdb8a4b3 Mon Sep 17 00:00:00 2001
From: Brennan Spellacy <brennanspellacy@gmail.com>
Date: Wed, 1 Jul 2020 20:08:32 -0700
Subject: [PATCH 05/17] Add required field

---
 rswag-specs/lib/rswag/specs/swagger_formatter.rb | 1 +
 test-app/swagger/v1/swagger.json                 | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb
index 0b15f12..69af771 100644
--- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb
+++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb
@@ -59,6 +59,7 @@ module Rswag
                   mime_list = value.dig(:consumes)
                   if value && schema_param && mime_list
                     value[:requestBody] = { content: {} } unless value.dig(:requestBody, :content)
+                    value[:requestBody][:required] = true if schema_param[:required]
                     mime_list.each do |mime|
                       value[:requestBody][:content][mime] = { schema: schema_param[:schema] }
                     end
diff --git a/test-app/swagger/v1/swagger.json b/test-app/swagger/v1/swagger.json
index 957206c..4c8afee 100644
--- a/test-app/swagger/v1/swagger.json
+++ b/test-app/swagger/v1/swagger.json
@@ -294,7 +294,8 @@
                 "type": "file"
               }
             }
-          }
+          },
+          "required": true
         }
       }
     }

From 347f9da32ef5897d23e0c21ab4e01411b7c3ef66 Mon Sep 17 00:00:00 2001
From: psmandzich <psmandzich@users.noreply.github.com>
Date: Tue, 21 Jul 2020 09:50:47 +0200
Subject: [PATCH 06/17] enable swagger empty body responses

---
 .../lib/rswag/specs/swagger_formatter.rb      |  2 +-
 .../rswag/specs/swagger_formatter_spec.rb     | 50 +++++++++++++++++++
 test-app/swagger/v1/swagger.json              | 40 ++++-----------
 3 files changed, 61 insertions(+), 31 deletions(-)

diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb
index 0b15f12..37ddd26 100644
--- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb
+++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb
@@ -129,9 +129,9 @@ module Rswag
       end
 
       def upgrade_content!(mime_list, target_node)
-        target_node.merge!(content: {})
         schema = target_node[:schema]
         return if mime_list.empty? || schema.nil?
+        target_node.merge!(content: {})
 
         mime_list.each do |mime_type|
           # TODO upgrade to have content-type specific schema
diff --git a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb
index 1a9fdf0..2ae0d05 100644
--- a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb
+++ b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb
@@ -127,6 +127,56 @@ module Rswag
             )
           end
 
+          context 'with empty content' do
+            let(:swagger_doc) do
+              {
+                openapi: '3.0.1',
+                basePath: '/foo',
+                schemes: ['http', 'https'],
+                host: 'api.example.com',
+                components: {
+                  securitySchemes: {
+                    myClientCredentials: {
+                      type: :oauth2,
+                      flow: :application,
+                      token_url: :somewhere
+                    },
+                    myAuthorizationCode: {
+                      type: :oauth2,
+                      flow: :accessCode,
+                      token_url: :somewhere
+                    },
+                    myImplicit: {
+                      type: :oauth2,
+                      flow: :implicit,
+                      token_url: :somewhere
+                    }
+                  }
+                }
+              }
+            end
+
+            it 'converts query and path params, type: to schema: { type: }' do
+              expect(swagger_doc.slice(:paths)).to match(
+                paths: {
+                  '/blogs' => {
+                    parameters: [{ schema: { type: :string } }],
+                    post: {
+                      parameters: [{ schema: { type: :string } }],
+                      summary: 'Creates a blog',
+                      responses: {
+                        '201' => {
+                          description: 'blog created',
+                          headers: { schema: { type: :string } }
+                        }
+                      }
+                    }
+                  }
+                }
+              )
+            end
+          end
+
           it 'converts basePath, schemas and host to urls' do
             expect(swagger_doc.slice(:servers)).to match(
               servers: {
diff --git a/test-app/swagger/v1/swagger.json b/test-app/swagger/v1/swagger.json
index 957206c..a5ea43b 100644
--- a/test-app/swagger/v1/swagger.json
+++ b/test-app/swagger/v1/swagger.json
@@ -21,14 +21,10 @@
         ],
         "responses": {
           "204": {
-            "description": "Valid credentials",
-            "content": {
-            }
+            "description": "Valid credentials"
           },
           "401": {
-            "description": "Invalid credentials",
-            "content": {
-            }
+            "description": "Invalid credentials"
           }
         }
       }
@@ -49,14 +45,10 @@
         ],
         "responses": {
           "204": {
-            "description": "Valid credentials",
-            "content": {
-            }
+            "description": "Valid credentials"
           },
           "401": {
-            "description": "Invalid credentials",
-            "content": {
-            }
+            "description": "Invalid credentials"
           }
         }
       }
@@ -80,14 +72,10 @@
         ],
         "responses": {
           "204": {
-            "description": "Valid credentials",
-            "content": {
-            }
+            "description": "Valid credentials"
           },
           "401": {
-            "description": "Invalid credentials",
-            "content": {
-            }
+            "description": "Invalid credentials"
           }
         }
       }
@@ -105,9 +93,7 @@
         ],
         "responses": {
           "201": {
-            "description": "blog created",
-            "content": {
-            }
+            "description": "blog created"
           },
           "422": {
             "description": "invalid request",
@@ -148,9 +134,7 @@
         ],
         "responses": {
           "406": {
-            "description": "unsupported accept header",
-            "content": {
-            }
+            "description": "unsupported accept header"
           }
         }
       }
@@ -252,9 +236,7 @@
             }
           },
           "404": {
-            "description": "blog not found",
-            "content": {
-            }
+            "description": "blog not found"
           }
         }
       }
@@ -282,9 +264,7 @@
         ],
         "responses": {
           "200": {
-            "description": "blog updated",
-            "content": {
-            }
+            "description": "blog updated"
           }
         },
         "requestBody": {

From b37c7905cd0154042aa39a8b94ba570a445ea694 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Mon, 12 Oct 2020 22:47:31 -0700
Subject: [PATCH 07/17] stub controller to help with future testing

---
 test-app/app/assets/javascripts/stubs.js     | 2 ++
 test-app/app/assets/stylesheets/stubs.css    | 4 ++++
 test-app/app/controllers/stubs_controller.rb | 9 +++++++++
 test-app/app/helpers/stubs_helper.rb         | 2 ++
 test-app/config/routes.rb                    | 2 ++
 5 files changed, 19 insertions(+)
 create mode 100644 test-app/app/assets/javascripts/stubs.js
 create mode 100644 test-app/app/assets/stylesheets/stubs.css
 create mode 100644 test-app/app/controllers/stubs_controller.rb
 create mode 100644 test-app/app/helpers/stubs_helper.rb

diff --git a/test-app/app/assets/javascripts/stubs.js b/test-app/app/assets/javascripts/stubs.js
new file mode 100644
index 0000000..dee720f
--- /dev/null
+++ b/test-app/app/assets/javascripts/stubs.js
@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.
diff --git a/test-app/app/assets/stylesheets/stubs.css b/test-app/app/assets/stylesheets/stubs.css
new file mode 100644
index 0000000..afad32d
--- /dev/null
+++ b/test-app/app/assets/stylesheets/stubs.css
@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/
diff --git a/test-app/app/controllers/stubs_controller.rb b/test-app/app/controllers/stubs_controller.rb
new file mode 100644
index 0000000..7a4acd9
--- /dev/null
+++ b/test-app/app/controllers/stubs_controller.rb
@@ -0,0 +1,9 @@
+class StubsController < ApplicationController
+  def index
+    render plain: 'OK'
+  end
+
+  def show
+    render plain: 'OK'
+  end
+end
diff --git a/test-app/app/helpers/stubs_helper.rb b/test-app/app/helpers/stubs_helper.rb
new file mode 100644
index 0000000..7ae9034
--- /dev/null
+++ b/test-app/app/helpers/stubs_helper.rb
@@ -0,0 +1,2 @@
+module StubsHelper
+end
diff --git a/test-app/config/routes.rb b/test-app/config/routes.rb
index 038f728..3107e95 100644
--- a/test-app/config/routes.rb
+++ b/test-app/config/routes.rb
@@ -9,6 +9,8 @@ TestApp::Application.routes.draw do
   post 'auth-tests/api-key', to: 'auth_tests#api_key'
   post 'auth-tests/basic-and-api-key', to: 'auth_tests#basic_and_api_key'
 
+  resources :stubs
+
   mount  Rswag::Api::Engine => 'api-docs'
   mount  Rswag::Ui::Engine => 'api-docs'
 end

From 7e1a79220cf6c33adc6e295e0e0d8005c9aa7996 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Mon, 12 Oct 2020 22:49:47 -0700
Subject: [PATCH 08/17] start standing up exhaustive output unit tests for
 OpenAPI v3

---
 test-app/spec/integration/openapi3_spec.rb | 273 +++++++++++++++++++++
 test-app/spec/swagger_helper.rb            |  63 +++++
 test-app/swagger/v3/openapi.json           | 139 +++++++++++
 3 files changed, 475 insertions(+)
 create mode 100644 test-app/spec/integration/openapi3_spec.rb
 create mode 100644 test-app/swagger/v3/openapi.json

diff --git a/test-app/spec/integration/openapi3_spec.rb b/test-app/spec/integration/openapi3_spec.rb
new file mode 100644
index 0000000..8d0d082
--- /dev/null
+++ b/test-app/spec/integration/openapi3_spec.rb
@@ -0,0 +1,273 @@
+require 'swagger_helper'
+require 'rswag/specs/swagger_formatter'
+
+# This spec file validates OpenAPI output generated by spec metadata.
+# Specifically here, we look at OpenApi 3 as documented at
+# https://swagger.io/docs/specification/about/
+
+RSpec.describe 'Generated OpenApi', type: :request, swagger_doc: 'v3/openapi.json' do
+  before do |example|
+    output = double('output').as_null_object
+    swagger_root = File.expand_path('tmp/swagger', __dir__)
+    config = double('config', swagger_root: swagger_root, get_swagger_doc: swagger_doc )
+    formatter = Rswag::Specs::SwaggerFormatter.new(output, config)
+    
+    example_group = OpenStruct.new(group: OpenStruct.new(metadata: example.metadata))
+    formatter.example_group_finished(example_group)
+  end
+
+  # Framework definition, to be overridden for contexts
+  let(:swagger_doc) do
+    { # That which would be defined in swagger_helper.rb
+      openapi: api_openapi,
+      basePath: api_base_path,
+      schemes: api_schemes,
+      host: api_host,
+      produces: api_produces,
+      components: api_components
+    }
+  end
+  let(:api_openapi) { '3.0.1' }
+  let(:api_base_path) { '/foo' }
+  let(:api_schemes) { ['https'] }
+  let(:api_host) { 'api.example.com' }
+  let(:api_produces) { ['application/json'] }
+  let(:api_components) { {} }
+
+  describe 'Basic Structure'
+  describe 'API Server and Base Path'
+
+  describe 'Media Types' do
+    path '/stubs' do
+      get 'a summary' do
+        tags 'Media Types'
+
+        response '200', 'OK' do
+          run_test!
+
+          it 'declares output as application/json' do
+            pending "Not yet implemented?"
+            tree = swagger_doc.dig(:paths, "/stubs", :get, :responses, '200', :content)
+            expect(tree).to have_key('application/json')
+          end
+        end
+      end
+    end
+  end
+
+  describe 'Paths and Operations'
+
+  describe 'Parameter Serialization' do
+    describe 'Path Parameters' do
+      path '/stubs/{a_param}' do
+        get 'a summary' do
+          tags 'Parameter Serialization: Query String'
+          produces 'application/json'
+
+          parameter(
+            name: 'a_param',
+            in: :path,
+          )
+          let(:a_param) { "42" }
+
+          response '200', 'OK' do
+            run_test!
+
+            it 'declares parameter in path' do
+              tree = swagger_doc.dig(:paths, "/stubs/{a_param}", :get, :parameters)
+              expect(tree.first[:name]).to eq('a_param')
+              expect(tree.first[:in]).to eq(:path)
+            end
+
+            it 'declares path parameters as required' do
+              tree = swagger_doc.dig(:paths, "/stubs/{a_param}", :get, :parameters)
+              expect(tree.first[:required]).to eq(true)
+            end
+          end
+        end
+      end
+    end
+
+    describe 'Query Parameters' do
+      path '/stubs' do
+        get 'a summary' do
+          tags 'Parameter Serialization: Query String'
+          produces 'application/json'
+
+          parameter(
+            name: 'a_param',
+            in: :query,
+          )
+          let(:a_param) { "a foo" }
+
+          response '200', 'OK' do
+            run_test!
+
+            it 'declares parameter in query string' do
+              tree = swagger_doc.dig(:paths, "/stubs", :get, :parameters)
+              expect(tree.first[:name]).to eq('a_param')
+              expect(tree.first[:in]).to eq(:query)
+            end
+          end
+
+          # TODO: Serialization (form/spaceDelimited/pipeDelimited/deepObject)
+        end
+      end
+    end
+
+    # TODO: Header
+    # TODO: Cookie
+    # TODO: Default values
+    # TODO: Enum
+    # TODO: Constant
+    # TODO: Empty/Nullable
+    # TODO: Examples
+    # TODO: Deprecated
+    # TODO: Common Parameters
+  end
+
+  describe 'Request Body'
+  describe 'Responses'
+  describe 'Data Models (Schemas)'
+  describe 'Examples'
+  describe 'Authentication'
+  describe 'Links'
+  describe 'Callbacks'
+  describe 'Components Section'
+  describe 'Using $ref'
+  describe 'Grouping Operations with Tags'
+
+
+  # path '/blogs' do
+  #   post 'Creates a blog' do
+  #     tags 'Blogs'
+  #     description 'Creates a new blog from provided data'
+  #     operationId 'createBlog'
+  #     consumes 'application/json'
+  #     produces 'application/json'
+  #     parameter name: :blog, in: :body, schema: { '$ref' => '#/definitions/blog' }
+
+  #     let(:blog) { { title: 'foo', content: 'bar' } }
+
+  #     response '201', 'blog created' do
+  #       # schema '$ref' => '#/definitions/blog'
+  #       run_test!
+  #     end
+
+  #     response '422', 'invalid request' do
+  #       schema '$ref' => '#/definitions/errors_object'
+
+  #       let(:blog) { { title: 'foo' } }
+  #       run_test! do |response|
+  #         expect(response.body).to include("can't be blank")
+  #       end
+
+  #       it 'outputs parameters' do
+  #         pp swagger_doc
+  #         params = swagger_doc.dig(:paths, "/blogs", :post, :parameters)
+  #         expect(params[0][:name]).to eq(:blog)
+  #       end
+  #     end
+  #   end
+
+  #   get 'Searches blogs' do
+  #     tags 'Blogs'
+  #     description 'Searches blogs by keywords'
+  #     operationId 'searchBlogs'
+  #     produces 'application/json'
+  #     parameter name: :keywords, in: :query, type: 'string'
+
+  #     let(:keywords) { 'foo bar' }
+
+  #     response '200', 'success' do
+  #       schema type: 'array', items: { '$ref' => '#/definitions/blog' }
+  #     end
+
+  #     response '406', 'unsupported accept header' do
+  #       let(:'Accept') { 'application/foo' }
+  #       run_test!
+  #     end
+  #   end
+  # end
+
+  # path '/blogs/flexible' do
+  #   post 'Creates a blog flexible body' do
+  #     tags 'Blogs'
+  #     description 'Creates a flexible blog from provided data'
+  #     operationId 'createFlexibleBlog'
+  #     consumes 'application/json'
+  #     produces 'application/json'
+
+  #     parameter name: :flexible_blog, in: :body, schema: {
+  #       oneOf: [
+  #         { '$ref' => '#/definitions/blog' },
+  #         { '$ref' => '#/definitions/flexible_blog' }
+  #       ]
+  #     }
+
+  #     let(:flexible_blog) { { blog: { headline: 'my headline', text: 'my text' } } }
+
+  #     response '201', 'flexible blog created' do
+  #       schema oneOf: [{ '$ref' => '#/definitions/blog' }, { '$ref' => '#/definitions/flexible_blog' }]
+  #       run_test!
+  #     end
+  #   end
+  # end
+
+  # path '/blogs/{id}' do
+  #   parameter name: :id, in: :path, type: :string
+
+  #   let(:id) { blog.id }
+  #   let(:blog) { Blog.create(title: 'foo', content: 'bar', thumbnail: 'thumbnail.png') }
+
+  #   get 'Retrieves a blog' do
+  #     tags 'Blogs'
+  #     description 'Retrieves a specific blog by id'
+  #     operationId 'getBlog'
+  #     produces 'application/json'
+
+  #     response '200', 'blog found' do
+  #       header 'ETag', type: :string
+  #       header 'Last-Modified', type: :string
+  #       header 'Cache-Control', type: :string
+
+  #       schema '$ref' => '#/definitions/blog'
+
+  #       examples 'application/json' => {
+  #         id: 1,
+  #         title: 'Hello world!',
+  #         content: 'Hello world and hello universe. Thank you all very much!!!',
+  #         thumbnail: 'thumbnail.png'
+  #       }
+
+  #       let(:id) { blog.id }
+  #       run_test!
+  #     end
+
+  #     response '404', 'blog not found' do
+  #       let(:id) { 'invalid' }
+  #       run_test!
+  #     end
+  #   end
+  # end
+
+  # path '/blogs/{id}/upload' do
+  #   parameter name: :id, in: :path, type: :string
+
+  #   let(:id) { blog.id }
+  #   let(:blog) { Blog.create(title: 'foo', content: 'bar') }
+
+  #   put 'Uploads a blog thumbnail' do
+  #     tags 'Blogs'
+  #     description 'Upload a thumbnail for specific blog by id'
+  #     operationId 'uploadThumbnailBlog'
+  #     consumes 'multipart/form-data'
+  #     parameter name: :file, :in => :formData, :type => :file, required: true
+
+  #     response '200', 'blog updated' do
+  #       let(:file) { Rack::Test::UploadedFile.new(Rails.root.join("spec/fixtures/thumbnail.png")) }
+  #       run_test!
+  #     end
+  #   end
+  # end
+end
diff --git a/test-app/spec/swagger_helper.rb b/test-app/spec/swagger_helper.rb
index 3f2e151..3b8dfae 100644
--- a/test-app/spec/swagger_helper.rb
+++ b/test-app/spec/swagger_helper.rb
@@ -77,6 +77,69 @@ RSpec.configure do |config|
           in: :query
         }
       }
+    },
+    'v3/openapi.json' => {
+      openapi: '3.0.0',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      },
+      paths: {},
+      servers: [
+        {
+          url: 'https://{defaultHost}',
+          variables: {
+            defaultHost: {
+              default: 'www.example.com'
+            }
+          }
+        }
+      ],
+      definitions: {
+        errors_object: {
+          type: 'object',
+          properties: {
+            errors: { '$ref' => '#/definitions/errors_map' }
+          }
+        },
+        errors_map: {
+          type: 'object',
+          additionalProperties: {
+            type: 'array',
+            items: { type: 'string' }
+          }
+        },
+        blog: {
+          type: 'object',
+          properties: {
+            id: { type: 'integer' },
+            title: { type: 'string' },
+            content: { type: 'string', 'x-nullable': true },
+            thumbnail: { type: 'string', 'x-nullable': true}
+          },
+          required: [ 'id', 'title' ]
+        },
+        flexible_blog: {
+          type: 'object',
+          properties: {
+            id: { type: 'integer' },
+            headline: { type: 'string' },
+            text: { type: 'string', nullable: true },
+            thumbnail: { type: 'string', nullable: true }
+          },
+          required: ['id', 'headline']
+        }
+      },
+      securityDefinitions: {
+        basic_auth: {
+          type: :basic
+        },
+        api_key: {
+          type: :apiKey,
+          name: 'api_key',
+          in: :query
+        }
+      }
     }
   }
 end
diff --git a/test-app/swagger/v3/openapi.json b/test-app/swagger/v3/openapi.json
new file mode 100644
index 0000000..97506c4
--- /dev/null
+++ b/test-app/swagger/v3/openapi.json
@@ -0,0 +1,139 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "API V1",
+    "version": "v1"
+  },
+  "paths": {
+    "/stubs": {
+      "get": {
+        "summary": "a summary",
+        "tags": [
+          "Parameter Serialization: Query String"
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "a_param",
+            "in": "query"
+          }
+        ]
+      }
+    },
+    "/stubs/{a_param}": {
+      "get": {
+        "summary": "a summary",
+        "tags": [
+          "Parameter Serialization: Query String"
+        ],
+        "parameters": [
+          {
+            "name": "a_param",
+            "in": "path",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+            }
+          }
+        }
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://{defaultHost}",
+      "variables": {
+        "defaultHost": {
+          "default": "www.example.com"
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "errors_object": {
+      "type": "object",
+      "properties": {
+        "errors": {
+          "$ref": "#/definitions/errors_map"
+        }
+      }
+    },
+    "errors_map": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "blog": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "title": {
+          "type": "string"
+        },
+        "content": {
+          "type": "string",
+          "x-nullable": true
+        },
+        "thumbnail": {
+          "type": "string",
+          "x-nullable": true
+        }
+      },
+      "required": [
+        "id",
+        "title"
+      ]
+    },
+    "flexible_blog": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer"
+        },
+        "headline": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string",
+          "nullable": true
+        },
+        "thumbnail": {
+          "type": "string",
+          "nullable": true
+        }
+      },
+      "required": [
+        "id",
+        "headline"
+      ]
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "basic_auth": {
+        "type": "basic"
+      },
+      "api_key": {
+        "type": "apiKey",
+        "name": "api_key",
+        "in": "query"
+      }
+    }
+  }
+}
\ No newline at end of file

From f6630cc7a612f72839aa8d0257e3263992eb657e Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Mon, 12 Oct 2020 22:50:48 -0700
Subject: [PATCH 09/17] fix a bug related to upgrade_request_type! translation

---
 rswag-specs/lib/rswag/specs/request_factory.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rswag-specs/lib/rswag/specs/request_factory.rb b/rswag-specs/lib/rswag/specs/request_factory.rb
index 2e8f3f1..30c423e 100644
--- a/rswag-specs/lib/rswag/specs/request_factory.rb
+++ b/rswag-specs/lib/rswag/specs/request_factory.rb
@@ -118,7 +118,7 @@ module Rswag
 
       def build_query_string_part(param, value)
         name = param[:name]
-        return "#{name}=#{value}" unless param[:type].to_sym == :array
+        return "#{name}=#{value}" unless param.dig(:schema, :type)&.to_sym == :array
 
         case param[:collectionFormat]
         when :ssv

From 68e64dba2c563f5c7a1357c0cf7a0aa87860dfd1 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Mon, 12 Oct 2020 22:53:18 -0700
Subject: [PATCH 10/17] OpenAPI currently at v 3.0.3

---
 test-app/spec/integration/openapi3_spec.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test-app/spec/integration/openapi3_spec.rb b/test-app/spec/integration/openapi3_spec.rb
index 8d0d082..7515ef1 100644
--- a/test-app/spec/integration/openapi3_spec.rb
+++ b/test-app/spec/integration/openapi3_spec.rb
@@ -27,7 +27,7 @@ RSpec.describe 'Generated OpenApi', type: :request, swagger_doc: 'v3/openapi.jso
       components: api_components
     }
   end
-  let(:api_openapi) { '3.0.1' }
+  let(:api_openapi) { '3.0.3' }
   let(:api_base_path) { '/foo' }
   let(:api_schemes) { ['https'] }
   let(:api_host) { 'api.example.com' }

From 91a27852f2f4786b4db5bbcf5d89f67158439be5 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Tue, 13 Oct 2020 09:17:15 -0700
Subject: [PATCH 11/17] more flex in this check

---
 rswag-specs/lib/rswag/specs/request_factory.rb | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rswag-specs/lib/rswag/specs/request_factory.rb b/rswag-specs/lib/rswag/specs/request_factory.rb
index 30c423e..523b50f 100644
--- a/rswag-specs/lib/rswag/specs/request_factory.rb
+++ b/rswag-specs/lib/rswag/specs/request_factory.rb
@@ -118,7 +118,8 @@ module Rswag
 
       def build_query_string_part(param, value)
         name = param[:name]
-        return "#{name}=#{value}" unless param.dig(:schema, :type)&.to_sym == :array
+        type = param[:type] || param.dig(:schema, :type)
+        return "#{name}=#{value}" unless type&.to_sym == :array
 
         case param[:collectionFormat]
         when :ssv

From d090516f481dc5ee4037b51294adedbaac861621 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Tue, 13 Oct 2020 16:24:51 -0700
Subject: [PATCH 12/17] properly list servers for openapi v3

---
 test-app/spec/integration/openapi3_spec.rb | 69 +++++++++++++++++++---
 1 file changed, 62 insertions(+), 7 deletions(-)

diff --git a/test-app/spec/integration/openapi3_spec.rb b/test-app/spec/integration/openapi3_spec.rb
index 7515ef1..051c464 100644
--- a/test-app/spec/integration/openapi3_spec.rb
+++ b/test-app/spec/integration/openapi3_spec.rb
@@ -20,22 +20,77 @@ RSpec.describe 'Generated OpenApi', type: :request, swagger_doc: 'v3/openapi.jso
   let(:swagger_doc) do
     { # That which would be defined in swagger_helper.rb
       openapi: api_openapi,
-      basePath: api_base_path,
-      schemes: api_schemes,
-      host: api_host,
+      info: {},
+      servers: api_servers,
       produces: api_produces,
       components: api_components
     }
   end
   let(:api_openapi) { '3.0.3' }
-  let(:api_base_path) { '/foo' }
-  let(:api_schemes) { ['https'] }
-  let(:api_host) { 'api.example.com' }
+  let(:api_servers) {[{ url: "https://api.example.com/foo" }]}
   let(:api_produces) { ['application/json'] }
   let(:api_components) { {} }
 
   describe 'Basic Structure'
-  describe 'API Server and Base Path'
+
+  describe 'API Server and Base Path' do
+    path '/stubs' do
+      get 'a summary' do
+        tags 'Server and Path'
+
+        response '200', 'OK' do
+          run_test!
+
+          it 'lists server' do
+            tree = swagger_doc.dig(:servers)
+            expect(tree).to eq([
+              { url: "https://api.example.com/foo" }
+            ])
+          end
+
+          context "multiple" do
+            let(:api_servers) {[
+              { url: "https://api.example.com/foo" },
+              { url: "http://api.example.com/foo" },
+            ]}
+
+            it 'lists servers' do
+              tree = swagger_doc.dig(:servers)
+              expect(tree).to eq([
+                { url: "https://api.example.com/foo" },
+                { url: "http://api.example.com/foo" }
+              ])
+            end
+          end
+
+          context "with variables" do
+            let(:api_servers) {[{
+              url: "https://{defaultHost}/foo",
+              variables: {
+                defaultHost: {
+                  default: "api.example.com" 
+                }
+              }
+            }]}
+
+            it 'lists server and variables' do
+              tree = swagger_doc.dig(:servers)
+              expect(tree).to eq([{
+                url: "https://{defaultHost}/foo",
+                variables: {
+                  defaultHost: {
+                    default: "api.example.com" 
+                  }
+                }
+              }])
+            end
+          end
+
+          # TODO: Enum variables, defaults, override at path/operation
+        end
+      end
+    end
+  end
 
   describe 'Media Types' do
     path '/stubs' do

From 3e10b09f23b5ee63b765b2487b474952a984e495 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Tue, 13 Oct 2020 16:27:32 -0700
Subject: [PATCH 13/17] swap deprecated SecurityDefinitions for SecuritySchemes

---
 test-app/spec/swagger_helper.rb | 36 ++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/test-app/spec/swagger_helper.rb b/test-app/spec/swagger_helper.rb
index 3b8dfae..ea72c4d 100644
--- a/test-app/spec/swagger_helper.rb
+++ b/test-app/spec/swagger_helper.rb
@@ -67,14 +67,16 @@ RSpec.configure do |config|
           required: ['id', 'headline']
         }
       },
-      securityDefinitions: {
-        basic_auth: {
-          type: :basic
-        },
-        api_key: {
-          type: :apiKey,
-          name: 'api_key',
-          in: :query
+      components: {
+        securitySchemes: {
+          basic_auth: {
+            type: :basic
+          },
+          api_key: {
+            type: :apiKey,
+            name: 'api_key',
+            in: :query
+          }
         }
       }
     },
@@ -130,14 +132,16 @@ RSpec.configure do |config|
           required: ['id', 'headline']
         }
       },
-      securityDefinitions: {
-        basic_auth: {
-          type: :basic
-        },
-        api_key: {
-          type: :apiKey,
-          name: 'api_key',
-          in: :query
+      components: {
+        securitySchemes: {
+          basic_auth: {
+            type: :basic
+          },
+          api_key: {
+            type: :apiKey,
+            name: 'api_key',
+            in: :query
+          }
         }
       }
     }

From ab457743a820d0544fd464f86a0920ba13a224e0 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Tue, 13 Oct 2020 16:28:40 -0700
Subject: [PATCH 14/17] also move away from deprecated type: basic

---
 test-app/spec/swagger_helper.rb  | 6 ++++--
 test-app/swagger/v1/swagger.json | 3 ++-
 test-app/swagger/v3/openapi.json | 3 ++-
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/test-app/spec/swagger_helper.rb b/test-app/spec/swagger_helper.rb
index ea72c4d..cadb592 100644
--- a/test-app/spec/swagger_helper.rb
+++ b/test-app/spec/swagger_helper.rb
@@ -70,7 +70,8 @@ RSpec.configure do |config|
       components: {
         securitySchemes: {
           basic_auth: {
-            type: :basic
+            type: :http,
+            scheme: :basic
           },
           api_key: {
             type: :apiKey,
@@ -135,7 +136,8 @@ RSpec.configure do |config|
       components: {
         securitySchemes: {
           basic_auth: {
-            type: :basic
+            type: :http,
+            scheme: :basic
           },
           api_key: {
             type: :apiKey,
diff --git a/test-app/swagger/v1/swagger.json b/test-app/swagger/v1/swagger.json
index 957206c..e18f579 100644
--- a/test-app/swagger/v1/swagger.json
+++ b/test-app/swagger/v1/swagger.json
@@ -377,7 +377,8 @@
   "components": {
     "securitySchemes": {
       "basic_auth": {
-        "type": "basic"
+        "type": "http",
+        "scheme": "basic"
       },
       "api_key": {
         "type": "apiKey",
diff --git a/test-app/swagger/v3/openapi.json b/test-app/swagger/v3/openapi.json
index 97506c4..90b9f18 100644
--- a/test-app/swagger/v3/openapi.json
+++ b/test-app/swagger/v3/openapi.json
@@ -127,7 +127,8 @@
   "components": {
     "securitySchemes": {
       "basic_auth": {
-        "type": "basic"
+        "type": "http",
+        "scheme": "basic"
       },
       "api_key": {
         "type": "apiKey",

From 0d1a742f6f3b65344946b6b6de49e25d38b89c82 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Sat, 17 Oct 2020 13:44:04 -0700
Subject: [PATCH 15/17] empty content is now pruned

---
 test-app/swagger/v3/openapi.json | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/test-app/swagger/v3/openapi.json b/test-app/swagger/v3/openapi.json
index 90b9f18..a344f69 100644
--- a/test-app/swagger/v3/openapi.json
+++ b/test-app/swagger/v3/openapi.json
@@ -13,9 +13,7 @@
         ],
         "responses": {
           "200": {
-            "description": "OK",
-            "content": {
-            }
+            "description": "OK"
           }
         },
         "parameters": [
@@ -41,9 +39,7 @@
         ],
         "responses": {
           "200": {
-            "description": "OK",
-            "content": {
-            }
+            "description": "OK"
           }
         }
       }

From 5a60dee838d6d8fe9543a6ed01dd2156e8299282 Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Sat, 17 Oct 2020 14:15:41 -0700
Subject: [PATCH 16/17] Add a spec for #342 body/required

---
 test-app/app/controllers/stubs_controller.rb |  4 ++++
 test-app/spec/integration/openapi3_spec.rb   | 23 ++++++++++++++++++-
 test-app/swagger/v3/openapi.json             | 24 ++++++++++++++++++++
 3 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/test-app/app/controllers/stubs_controller.rb b/test-app/app/controllers/stubs_controller.rb
index 7a4acd9..8b8ec8f 100644
--- a/test-app/app/controllers/stubs_controller.rb
+++ b/test-app/app/controllers/stubs_controller.rb
@@ -3,6 +3,10 @@ class StubsController < ApplicationController
     render plain: 'OK'
   end
 
+  def create
+    render plain: 'OK'
+  end
+
   def show
     render plain: 'OK'
   end
diff --git a/test-app/spec/integration/openapi3_spec.rb b/test-app/spec/integration/openapi3_spec.rb
index 051c464..d3e5b5f 100644
--- a/test-app/spec/integration/openapi3_spec.rb
+++ b/test-app/spec/integration/openapi3_spec.rb
@@ -181,7 +181,28 @@ RSpec.describe 'Generated OpenApi', type: :request, swagger_doc: 'v3/openapi.jso
     # TODO: Common Parameters
   end
 
-  describe 'Request Body'
+  describe 'Request Body' do
+    path '/stubs' do
+      post 'body is required' do
+        tags 'Media Types'
+        consumes 'multipart/form-data'
+        parameter name: :file, :in => :formData, :type => :file, required: true
+
+        let(:file) { Rack::Test::UploadedFile.new(Rails.root.join("spec/fixtures/thumbnail.png")) }
+
+        response '200', 'OK' do
+          run_test!
+
+          it 'declares requestBody is required' do
+            pending "This output is massaged in SwaggerFormatter#stop, and isn't quite ready here to assert"
+            tree = swagger_doc.dig(:paths, "/stubs", :post, :requestBody)
+            expect(tree[:required]).to eq(true)
+          end
+        end
+      end
+    end
+  end
+
   describe 'Responses'
   describe 'Data Models (Schemas)'
   describe 'Examples'
diff --git a/test-app/swagger/v3/openapi.json b/test-app/swagger/v3/openapi.json
index a344f69..19983c0 100644
--- a/test-app/swagger/v3/openapi.json
+++ b/test-app/swagger/v3/openapi.json
@@ -22,6 +22,30 @@
             "in": "query"
           }
         ]
+      },
+      "post": {
+        "summary": "body is required",
+        "tags": [
+          "Media Types"
+        ],
+        "parameters": [
+
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "requestBody": {
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "file"
+              }
+            }
+          },
+          "required": true
+        }
       }
     },
     "/stubs/{a_param}": {

From 206c088d742e1f323dc32eceef19548ffcde85cc Mon Sep 17 00:00:00 2001
From: Jamie Macey <jamie.git@tracefunc.com>
Date: Sat, 17 Oct 2020 14:16:21 -0700
Subject: [PATCH 17/17] WIP-branch changelog updates

---
 CHANGELOG.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c79df18..75036cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,15 +1,17 @@
 # rswag
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 ### Added
+- RequestBody now supports the `required` flag [#342](https://github.com/rswag/rswag/pull/342)
 ### Changed
 ### Deprecated
 ### Removed
 ### Fixed
+- Fix response example rendering [#330](https://github.com/rswag/rswag/pull/330)
+- Fix empty content block [#347](https://github.com/rswag/rswag/pull/347)
 ### Security
 
 ## [2.3.1] - 2020-04-08