Adds support for proper requestBody examples. Adds mechanism to allow for adding additional ways to add request body examples

Can add externalValue or  it will work and produce valid swagger spec.

The Symbol name matching the let parameter is always required

test-app/app/controllers/blogs_controller.rb

@@ -19,6 +19,14 @@ class BlogsController < ApplicationController
     respond_with @blog
   end
 
+  # POST /blogs/alternate
+  def alternate_create
+
+    # contrived example to show different :examples in the requestBody section
+    @blog = Blog.create(params.require(:blog).permit(:title, :content))
+    respond_with @blog
+  end
+
   # Put /blogs/1
   def upload
     @blog = Blog.find_by_id(params[:id])

test-app/config/routes.rb

@@ -1,6 +1,7 @@
 TestApp::Application.routes.draw do
 
   post '/blogs/flexible', to: 'blogs#flexible_create'
+  post '/blogs/alternate', to: 'blogs#alternate_create'
   resources :blogs
   put '/blogs/:id/upload', to: 'blogs#upload'
 

test-app/spec/integration/blogs_spec.rb

@@ -80,6 +80,32 @@ describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
     end
   end
 
+  path '/blogs/alternate' do
+    post 'Creates a blog - different :examples in requestBody' do
+      tags 'Blogs'
+      description 'Creates a new blog from provided data'
+      operationId 'createAlternateBlog'
+      consumes 'application/json'
+      produces 'application/json'
+
+      # NOTE: the externalValue: http://... is valid 3.0 spec, but swagger-UI does NOT support it yet
+      # https://github.com/swagger-api/swagger-ui/issues/5433
+      request_body_json schema: { '$ref' => '#/components/schemas/blog' },
+                        examples: [:blog, {name: :external_blog,
+                                           externalValue: 'http://api.sample.org/myjson_example'},
+                                          {name: :another_example,
+                                           '$ref' => '#/components/examples/flexible_blog_example'}]
+
+      let(:blog) { { blog: { title: 'alt title', content: 'alt bar' } } }
+
+      response '201', 'blog created' do
+        schema '$ref' => '#/components/schemas/blog'
+        run_test!
+      end
+    end
+  end
+
+
 
   path '/blogs/{id}' do
 

test-app/spec/swagger_helper.rb

@@ -69,6 +69,16 @@ RSpec.configure do |config|
               required: %w[id headline]
           }
         },
+        examples: {
+            flexible_blog_example: {
+                summary: 'Sample example of a flexible blog',
+                value: {
+                    id:  1,
+                    headline: 'This is a headline',
+                    text: 'Some sample text'
+                }
+            }
+        },
         securitySchemes: {
           basic_auth: {
             type: :http,

test-app/swagger/v1/swagger.json

@@ -258,6 +258,63 @@
         }
       }
     },
+    "/blogs/alternate": {
+      "post": {
+        "summary": "Creates a blog - different :examples in requestBody",
+        "tags": [
+          "Blogs"
+        ],
+        "description": "Creates a new blog from provided data",
+        "operationId": "createAlternateBlog",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "examples": {
+                "blog": {
+                  "value": {
+                    "blog": {
+                      "title": "alt title",
+                      "content": "alt bar"
+                    }
+                  }
+                },
+                "external_blog": {
+                  "externalValue": "http://api.sample.org/myjson_example"
+                },
+                "another_example": {
+                  "$ref": "#/components/examples/flexible_blog_example"
+                }
+              },
+              "schema": {
+                "$ref": "#/components/schemas/blog"
+              }
+            }
+          }
+        },
+        "parameters": [
+
+        ],
+        "responses": {
+          "201": {
+            "description": "blog created",
+            "content": {
+              "application/json": {
+                "example": {
+                  "id": 1,
+                  "title": "alt title",
+                  "content": "alt bar",
+                  "thumbnail": null
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/blog"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/blogs/{id}": {
       "get": {
         "summary": "Retrieves a blog",
@@ -435,6 +492,16 @@
         ]
       }
     },
+    "examples": {
+      "flexible_blog_example": {
+        "summary": "Sample example of a flexible blog",
+        "value": {
+          "id": 1,
+          "headline": "This is a headline",
+          "text": "Some sample text"
+        }
+      }
+    },
     "securitySchemes": {
       "basic_auth": {
         "type": "http",