Merge pull request #475 from rswag/fix/workflow

Fix GH Actions being unable to bundle

.github/workflows/ruby.yml

@@ -0,0 +1,60 @@
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [2.6, 2.7, truffleruby-head]
+        rails: [5.2.4.4, 6.0.3.4]
+    env:
+      RAILS_VERSION: ${{ matrix.rails }}
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with: { ruby-version: 2.6 }
+
+    - uses: actions/cache@v2
+      id: cache
+      with:
+        path: |
+          rswag-ui/node_modules
+          vendor/bundle
+        key: ${{ runner.os }}-ruby_${{ matrix.ruby }}-rails_${{ matrix.rails }}-${{ hashFiles('Gemfile', '**/package-lock.json') }}
+
+    - name: Install dependencies
+      run: |
+        gem update --system
+        bundle install
+        cd rswag-ui && npm install
+
+    - name: rswag-api
+      run: |
+        cd rswag-api
+        bundle exec rspec
+
+    - name: rswag-specs
+      if: success() || failure()
+      run: |
+        cd rswag-specs
+        bundle exec rspec
+
+    - name: rswag-ui
+      if: success() || failure()
+      run: |
+        cd rswag-ui
+        bundle exec rspec
+
+    - name: test-app
+      if: success() || failure()
+      run: |
+        cd test-app
+        bundle exec rake db:migrate db:test:prepare
+        bundle exec rspec

.ruby-version

@@ -1 +1 @@
-2.6.3
+2.7.2

CHANGELOG.md

@@ -1,16 +1,35 @@
 # 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
+
 ### Changed
-### Deprecated
-### Removed
+- Update swagger-ui to 3.52.5
+
+## [2.4.0] - 2021-02-09
+### Added
+- Added `SWAGGER_DRY_RUN` env variable [#274](https://github.com/rswag/rswag/pull/274)
+
+## [2.3.3] - 2021-02-07
+
 ### Fixed
-### Security
+- Include response examples [#394](https://github.com/rswag/rswag/pull/394)
+
+### Changed
+- Update swagger-ui to 3.42.0
+
+## [2.3.2] - 2021-01-27
+### Added
+- RequestBody now supports the `required` flag [#342](https://github.com/rswag/rswag/pull/342)
+### 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)
+
+## [2.3.1] - 2020-04-08
+### Fixed
+- Remove require for byebug [#295](https://github.com/rswag/rswag/issues/295)
 
 ## [2.3.0] - 2020-04-05
 ### Added
@@ -24,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update swagger-ui version to 3.23.11 [#239](https://github.com/rswag/rswag/pull/239)
 - Rails constraint moved from < 6.1 to < 7 [#253](https://github.com/rswag/rswag/pull/253)
 - Swaggerize now outputs base RSpec text on completion to avoid silent failures [#293](https://github.com/rswag/rswag/pull/293)
+- Update swagger-ui version to 3.28.0
 
 ## [2.2.0] - 2019-11-01
 ### Added

CONTRIBUTING.md

@@ -57,11 +57,11 @@ Push to your fork and [submit a Pull Request][pr].
 
 ## Updating Swagger UI
 
-Find the latest versions of swagger-ui here:  
+Find the latest versions of swagger-ui here:
 https://github.com/swagger-api/swagger-ui/releases
 
 Update the swagger-ui-dist version in the rswag-ui dependencies
-```  
+```
 ./rswag-ui/package.json
 ```
 

Gemfile

@@ -25,23 +25,25 @@ end
 gem 'rswag-api', path: './rswag-api'
 gem 'rswag-ui', path: './rswag-ui'
 
+group :development, :test do
+  gem 'rswag-specs', path: './rswag-specs'
+end
+
 group :test do
   gem 'capybara'
   gem 'geckodriver-helper'
   gem 'generator_spec'
   gem 'rspec-rails'
   gem 'selenium-webdriver'
-  gem 'rswag-specs', path: './rswag-specs'
   gem 'test-unit'
 end
 
 group :development do
-  gem 'rswag-specs', path: './rswag-specs'
   gem 'rubocop'
 end
 
 group :assets do
-  gem 'therubyracer'
+  gem 'mini_racer'
   gem 'uglifier'
 end
 

MIT-LICENCE

@@ -0,0 +1,20 @@
+Copyright 2015 domaindrivendev
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -5,6 +5,8 @@ rswag
 
 OpenApi 3.0 and Swagger 2.0 compatible!
 
+Seeking maintainers! Got a pet-bug that needs fixing? Just let us know in your issue/pr that you'd like to step up to help.
+
 Rswag extends rspec-rails "request specs" with a Swagger-based DSL for describing and testing API operations. You describe your API operations with a succinct, intuitive syntax, and it automaticaly runs the tests. Once you have green tests, run a rake task to auto-generate corresponding Swagger files and expose them as YAML or JSON endpoints. Rswag also provides an embedded version of the awesome [swagger-ui](https://github.com/swagger-api/swagger-ui) that's powered by the exposed file. This toolchain makes it seamless to go from integration specs, which youre probably doing in some form already, to living documentation for your API consumers.
 
 Api Rswag creates [Swagger](http://swagger.io) tooling for Rails API's. Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests.
@@ -18,7 +20,8 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
 
 |Rswag Version|Swagger (OpenAPI) Spec.|swagger-ui|
 |----------|----------|----------|
-|[master](https://github.com/rswag/rswag/tree/master)|3.0.3|3.23.11|
+|[master](https://github.com/rswag/rswag/tree/master)|3.0.3|3.52.5|
+|[2.3.0](https://github.com/rswag/rswag/tree/2.3.0)|3.0.3|3.23.11|
 |[2.2.0](https://github.com/rswag/rswag/tree/2.2.0)|2.0|3.18.2|
 |[1.6.0](https://github.com/rswag/rswag/tree/1.6.0)|2.0|2.2.5|
 
@@ -135,7 +138,7 @@ There is also a generator which can help get you started `rails generate rspec:s
       path '/blogs/{id}' do
 
         get 'Retrieves a blog' do
-          tags 'Blogs'
+          tags 'Blogs', 'Another Tag'
           produces 'application/json', 'application/xml'
           parameter name: :id, in: :path, type: :string
 
@@ -362,8 +365,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
@@ -415,7 +418,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'
@@ -436,11 +439,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 ##
@@ -478,9 +481,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
@@ -515,6 +518,15 @@ config.swagger_docs = {
             thumbnail: { type: 'string', nullable: true }
           },
           required: %w[id title]
+        },
+        new_blog: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            content: { type: 'string', nullable: true },
+            thumbnail: { type: 'string', format: 'binary', nullable: true }
+          },
+          required: %w[title]
         }
       }
     }
@@ -528,6 +540,8 @@ describe 'Blogs API' do
 
     post 'Creates a blog' do
 
+      parameter name: :new_blog, in: :body, schema: { '$ref' => '#/components/schemas/new_blog' }
+
       response 422, 'invalid request' do
         schema '$ref' => '#/components/schemas/errors_object'
   ...
@@ -548,7 +562,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
@@ -596,19 +610,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
+#### Dry Run Option ####
 
-<!-- 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. 
-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. -->
+The `--dry-run` option is enabled by default for Rspec 3, but if you need to
+disable it you can use the environment varible `SWAGGER_DRY_RUN=0` during the
+generation command or add the following to your `config/environments/test.rb`:
 
-Add to config/environments/test.rb:
 ```ruby
 RSpec.configure do |config|
   config.swagger_dry_run = false
@@ -644,8 +659,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' }
@@ -681,7 +696,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```.
@@ -691,7 +706,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": {
@@ -725,9 +740,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 #####
 
@@ -825,7 +840,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
 ```
@@ -897,6 +912,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.
-

rswag-api/rswag-api.gemspec

@@ -9,11 +9,11 @@ Gem::Specification.new do |s|
   s.authors     = ['Richie Morris', 'Greg Myers', 'Jay Danielian']
   s.email       = ['domaindrivendev@gmail.com']
   s.homepage    = 'https://github.com/rswag/rswag'
-  s.summary     = 'A Rails Engine that exposes Swagger files as JSON endpoints'
-  s.description = 'Open up your API to the phenomenal Swagger ecosystem by exposing Swagger files, that describe your service, as JSON endpoints'
+  s.summary     = 'A Rails Engine that exposes OpenAPI (formerly called Swagger) files as JSON endpoints'
+  s.description = 'Open up your API to the phenomenal OpenAPI ecosystem by exposing OpenAPI files, that describe your service, as JSON endpoints. More about the OpenAPI initiative here: http://spec.openapis.org/'
   s.license     = 'MIT'
 
   s.files = Dir['{lib}/**/*'] + ['MIT-LICENSE', 'Rakefile']
 
-  s.add_dependency 'railties', '>= 3.1', '< 7.0'
+  s.add_dependency 'railties', '>= 3.1', '< 7.1'
 end

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

rswag-specs/lib/rswag/route_parser.rb

@@ -11,7 +11,7 @@ module Rswag
     def routes
       ::Rails.application.routes.routes.select do |route|
         route.defaults[:controller] == controller
-      end.each_with_object({}) do |tree, route|
+      end.each_with_object({}) do |route, tree|
         path = path_from(route)
         verb = verb_from(route)
         tree[path] ||= { params: params_from(route), actions: {} }

rswag-specs/lib/rswag/specs/configuration.rb

@@ -28,9 +28,11 @@ module Rswag
       end
 
       def swagger_dry_run
-        @swagger_dry_run ||= begin
-          @rspec_config.swagger_dry_run.nil? || @rspec_config.swagger_dry_run
+        return @swagger_dry_run if defined? @swagger_dry_run
+        if ENV.key?('SWAGGER_DRY_RUN')
+          @rspec_config.swagger_dry_run = ENV['SWAGGER_DRY_RUN'] == '1'
         end
+        @swagger_dry_run = @rspec_config.swagger_dry_run.nil? || @rspec_config.swagger_dry_run
       end
 
       def swagger_format

rswag-specs/lib/rswag/specs/example_group_helpers.rb

@@ -72,7 +72,10 @@ 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
 
       def run_test!(&block)

rswag-specs/lib/rswag/specs/request_factory.rb

@@ -3,7 +3,6 @@
 require 'active_support/core_ext/hash/slice'
 require 'active_support/core_ext/hash/conversions'
 require 'json'
-require 'byebug'
 
 module Rswag
   module Specs
@@ -119,7 +118,8 @@ module Rswag
 
       def build_query_string_part(param, value)
         name = param[:name]
-        return "#{name}=#{value}" unless param[:type].to_sym == :array
+        type = param[:type] || param.dig(:schema, :type)
+        return "#{name}=#{value}" unless type&.to_sym == :array
 
         case param[:collectionFormat]
         when :ssv
@@ -194,12 +194,36 @@ module Rswag
 
       def build_json_payload(parameters, example)
         body_param = parameters.select { |p| p[:in] == :body }.first
-        body_param ? example.send(body_param[:name]).to_json : nil
+
+        return nil unless body_param
+
+        raise(MissingParameterError, body_param[:name]) unless example.respond_to?(body_param[:name])
+
+        example.send(body_param[:name]).to_json
       end
 
       def doc_version(doc)
         doc[:openapi] || doc[:swagger] || '3'
       end
     end
+
+    class MissingParameterError < StandardError
+      attr_reader :body_param
+
+      def initialize(body_param)
+        @body_param = body_param
+      end
+
+      def message
+        <<~MSG
+          Missing parameter '#{body_param}'
+
+          Please check your spec. It looks like you defined a body parameter,
+          but did not declare usage via let. Try adding:
+
+              let(:#{body_param}) {}
+        MSG
+      end
+    end
   end
 end

rswag-specs/lib/rswag/specs/response_validator.rb

@@ -50,7 +50,11 @@ module Rswag
           .merge(schemas)
 
         errors = JSON::Validator.fully_validate(validation_schema, body)
-        raise UnexpectedResponse, "Expected response body to match schema: #{errors[0]}" if errors.any?
+        return unless errors.any?
+
+        raise UnexpectedResponse,
+              "Expected response body to match schema: #{errors[0]}\n" \
+              "Response body: #{JSON.pretty_generate(JSON.parse(body))}"
       end
 
       def definitions_or_component_schemas(swagger_doc, version)
@@ -62,7 +66,7 @@ module Rswag
             swagger_doc.slice(:definitions)
           else
             components = swagger_doc[:components] || {}
-            { components: { schemas: components[:schemas] } }
+            { components: components }
           end
         end
       end

rswag-specs/lib/rswag/specs/swagger_formatter.rb

@@ -56,9 +56,10 @@ module Rswag
                 is_hash = value.is_a?(Hash)
                 if is_hash && value.dig(:parameters)
                   schema_param = value.dig(:parameters)&.find { |p| (p[:in] == :body || p[:in] == :formData) && p[:schema] }
-                  mime_list = value.dig(:consumes)
+                  mime_list = value.dig(:consumes) || doc[: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
@@ -129,13 +130,13 @@ 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[:content] ||= {}
         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
 

rswag-specs/rswag-specs.gemspec

@@ -9,13 +9,13 @@ Gem::Specification.new do |s|
   s.authors     = ['Richie Morris', 'Greg Myers', 'Jay Danielian']
   s.email       = ['domaindrivendev@gmail.com']
   s.homepage    = 'https://github.com/rswag/rswag'
-  s.summary     = 'A Swagger-based DSL for rspec-rails & accompanying rake task for generating Swagger files'
-  s.description = 'Simplify API integration testing with a succinct rspec DSL and generate Swagger files directly from your rspecs'
+  s.summary     = 'An OpenAPI-based (formerly called Swagger) DSL for rspec-rails & accompanying rake task for generating OpenAPI specification files'
+  s.description = 'Simplify API integration testing with a succinct rspec DSL and generate OpenAPI specification files directly from your rspecs. More about the OpenAPI initiative here: http://spec.openapis.org/'
   s.license     = 'MIT'
 
   s.files = Dir['{lib}/**/*'] + ['MIT-LICENSE', 'Rakefile']
 
-  s.add_dependency 'activesupport', '>= 3.1', '< 7.0'
-  s.add_dependency 'railties', '>= 3.1', '< 7.0'
+  s.add_dependency 'activesupport', '>= 3.1', '< 7.1'
+  s.add_dependency 'railties', '>= 3.1', '< 7.1'
   s.add_dependency 'json-schema', '~> 2.2'
 end

rswag-specs/spec/rswag/route_parser_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+RSpec.describe Rswag::RouteParser do
+  describe "#routes" do
+    let(:controller) { "api/v1/posts" }
+    subject { described_class.new(controller) }
+
+    let(:routes) do
+      [
+        double(
+          defaults: {
+            controller: controller
+          },
+          path: double(
+            spec: double(
+              to_s: "/api/v1/posts/:id(.:format)"
+            )
+          ),
+          verb: "GET",
+          requirements: {
+            action: "show",
+            controller: "api/v1/posts"
+          },
+          segments: ["id", "format"]
+        )  
+      ]
+    end
+
+    let(:expectation) do
+      {
+        "/api/v1/posts/{id}" => { 
+          params: ["id"],
+          actions: {
+            "get" => {
+              summary: "show post"
+            }
+          }
+        }
+      }
+    end
+
+    before do
+      allow(::Rails).to receive_message_chain("application.routes.routes") { routes }
+    end
+
+    it "returns correct routes" do
+      expect(subject.routes).to eq(expectation)
+    end
+  end
+end

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

rswag-specs/spec/rswag/specs/request_factory_spec.rb

@@ -160,6 +160,21 @@ module Rswag
             end
           end
 
+          context 'missing body parameter' do
+            before do
+              metadata[:operation][:parameters] = [{ name: 'comment', in: :body, schema: { type: 'object' } }]
+              allow(example).to receive(:comment).and_raise(NoMethodError, "undefined method 'comment'")
+              allow(example).to receive(:respond_to?).with(:'Content-Type')
+              allow(example).to receive(:respond_to?).with('comment').and_return(false)
+            end
+
+            it 'uses the referenced metadata to build the request' do
+              expect do
+                request[:payload]
+              end.to raise_error(Rswag::Specs::MissingParameterError, /Missing parameter 'comment'/)
+            end
+          end
+
           context 'form payload' do
             before do
               metadata[:operation][:consumes] = ['multipart/form-data']

rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb

@@ -11,6 +11,8 @@ module Rswag
       # Mock out some infrastructure
       before do
         allow(config).to receive(:swagger_root).and_return(swagger_root)
+
+        allow(ActiveSupport::Deprecation).to receive(:warn) # Silence deprecation output from specs
       end
       let(:config) { double('config') }
       let(:output) { double('output').as_null_object }
@@ -26,10 +28,11 @@ module Rswag
           {
             path_item: { template: '/blogs', parameters: [{ type: :string }] },
             operation: { verb: :post, summary: 'Creates a blog', parameters: [{ type: :string }] },
-            response: { code: '201', description: 'blog created', headers: { type: :string }, schema: { '$ref' => '#/definitions/blog' } },
+            response: response_metadata,
             document: document
           }
         end
+        let(:response_metadata) { { code: '201', description: 'blog created', headers: { type: :string }, schema: { '$ref' => '#/definitions/blog' } } }
 
         context 'with the document tag set to false' do
           let(:swagger_doc) { { swagger: '2.0' } }
@@ -127,6 +130,97 @@ module Rswag
             )
           end
 
+          context 'with response example' do
+            let(:response_metadata) do
+              {
+                code: '201',
+                description: 'blog created',
+                headers: { type: :string },
+                content: { 'application/json' => { example: { foo: :bar } } },
+                schema: { '$ref' => '#/definitions/blog' }
+              }
+            end
+
+            it 'adds example to definition' 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' => {
+                          content: {
+                            'application/vnd.my_mime' => {
+                              schema: { '$ref' => '#/definitions/blog' }
+                            },
+                            'application/json' => {
+                              schema: { '$ref' => '#/definitions/blog' },
+                              example: { foo: :bar }
+                            }
+                          },
+                          description: 'blog created',
+                          headers: { schema: { type: :string } }
+                        }
+                      }
+                    }
+                  }
+                }
+              )
+            end
+          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: {

rswag-ui/package-lock.json

@@ -5,9 +5,9 @@
   "requires": true,
   "dependencies": {
     "swagger-ui-dist": {
-      "version": "3.23.11",
-      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.23.11.tgz",
-      "integrity": "sha512-ipENHHH/sqpngTpHXUwg55eAOZ7b2UVayUwwuWPA6nQSPhjBVXX4zOPpNKUwQIFOl3oIwVvZF7mqoxH7pMgVzA=="
+      "version": "3.52.5",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.52.5.tgz",
+      "integrity": "sha512-8z18eX8G/jbTXYzyNIaobrnD7PSN7yU/YkSasMmajrXtw0FGS64XjrKn5v37d36qmU3o1xLeuYnktshRr7uIFw=="
     }
   }
 }

rswag-ui/package.json

@@ -3,6 +3,6 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "swagger-ui-dist": "3.23.11"
+    "swagger-ui-dist": "3.52.5"
   }
 }

rswag-ui/rswag-ui.gemspec

@@ -9,12 +9,12 @@ Gem::Specification.new do |s|
   s.authors     = ['Richie Morris', 'Greg Myers', 'Jay Danielian']
   s.email       = ['domaindrivendev@gmail.com']
   s.homepage    = 'https://github.com/rswag/rswag'
-  s.summary     = 'A Rails Engine that includes swagger-ui and powers it from configured Swagger endpoints'
-  s.description = 'Expose beautiful API documentation, powered by Swagger JSON endpoints, including a UI to explore and test operations'
+  s.summary     = 'A Rails Engine that includes swagger-ui and powers it from configured OpenAPI (formerly named Swagger) endpoints'
+  s.description = 'Expose beautiful API documentation, powered by Swagger JSON endpoints, including a UI to explore and test operations. More about the OpenAPI initiative here: http://spec.openapis.org/'
   s.license     = 'MIT'
 
   s.files = Dir.glob('{lib,node_modules}/**/*') + ['MIT-LICENSE', 'Rakefile' ]
 
-  s.add_dependency 'actionpack', '>=3.1', '< 7.0'
-  s.add_dependency 'railties', '>= 3.1', '< 7.0'
+  s.add_dependency 'actionpack', '>=3.1', '< 7.1'
+  s.add_dependency 'railties', '>= 3.1', '< 7.1'
 end

rswag/rswag.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ['Richie Morris', 'Greg Myers', 'Jay Danielian']
   s.email       = ['domaindrivendev@gmail.com']
   s.homepage    = 'https://github.com/rswag/rswag'
-  s.summary     = 'Swagger tooling for Rails APIs'
-  s.description = 'Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests'
+  s.summary     = 'OpenAPI (formerly named Swagger) tooling for Rails APIs'
+  s.description = 'Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests. OpenAPI 2 and 3 supported. More about the OpenAPI initiative here: http://spec.openapis.org/'
   s.license     = 'MIT'
 
   s.files = Dir['{lib}/**/*'] + [ 'MIT-LICENSE' ]

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.

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.
+*/

test-app/app/controllers/blogs_controller.rb

@@ -32,7 +32,7 @@ class BlogsController < ApplicationController
     @blog = Blog.find_by_id(params[:id])
     return head :not_found if @blog.nil?
     @blog.thumbnail = save_uploaded_file params[:file]
-    head @blog.save ? :ok : :unprocsessible_entity
+    head @blog.save ? :ok : :unprocessable_entity
   end
 
   # GET /blogs

test-app/app/controllers/stubs_controller.rb

@@ -0,0 +1,13 @@
+class StubsController < ApplicationController
+  def index
+    render plain: 'OK'
+  end
+
+  def create
+    render plain: 'OK'
+  end
+
+  def show
+    render plain: 'OK'
+  end
+end

test-app/app/helpers/stubs_helper.rb

@@ -0,0 +1,2 @@
+module StubsHelper
+end

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

test-app/spec/features/swagger_ui_spec.rb

@@ -3,6 +3,7 @@ require 'rails_helper'
 RSpec.feature 'swagger-ui', js: true do
 
   scenario 'browsing api-docs' do
+    skip "Needs work to run on others' machines"
     visit '/api-docs'
 
     expect(page).to have_content('GET /blogs Searches blogs', normalize_ws: true)

test-app/spec/integration/auth_tests_spec.rb

@@ -3,6 +3,10 @@
 require 'swagger_helper'
 
 RSpec.describe 'Auth Tests API', type: :request, swagger_doc: 'v1/swagger.json' do
+  before do
+    allow(ActiveSupport::Deprecation).to receive(:warn) # Silence deprecation output from specs
+  end
+
   path '/auth-tests/basic' do
     post 'Authenticates with basic auth' do
       tags 'Auth Tests'

test-app/spec/integration/blogs_spec.rb

@@ -3,6 +3,10 @@ require 'swagger_helper'
 RSpec.describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do
   let(:api_key) { 'fake_key' }
 
+  before do
+    allow(ActiveSupport::Deprecation).to receive(:warn) # Silence deprecation output from specs
+  end
+
   path '/blogs' do
     post 'Creates a blog' do
       tags 'Blogs'

test-app/spec/integration/openapi3_spec.rb

@@ -0,0 +1,349 @@
+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,
+      info: {},
+      servers: api_servers,
+      produces: api_produces,
+      components: api_components
+    }
+  end
+  let(:api_openapi) { '3.0.3' }
+  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' 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
+      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' 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'
+  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

test-app/spec/swagger_helper.rb

@@ -67,14 +67,83 @@ RSpec.configure do |config|
           required: ['id', 'headline']
         }
       },
-      securityDefinitions: {
-        basic_auth: {
-          type: :basic
+      components: {
+        securitySchemes: {
+          basic_auth: {
+            type: :http,
+            scheme: :basic
+          },
+          api_key: {
+            type: :apiKey,
+            name: 'api_key',
+            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' }
+          }
         },
-        api_key: {
-          type: :apiKey,
-          name: 'api_key',
-          in: :query
+        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: :http,
+            scheme: :basic
+          },
+          api_key: {
+            type: :apiKey,
+            name: 'api_key',
+            in: :query
+          }
         }
       }
     }

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"
           }
         }
       }
@@ -235,16 +219,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"
                 }
@@ -252,9 +234,7 @@
             }
           },
           "404": {
-            "description": "blog not found",
-            "content": {
-            }
+            "description": "blog not found"
           }
         }
       }
@@ -282,9 +262,7 @@
         ],
         "responses": {
           "200": {
-            "description": "blog updated",
-            "content": {
-            }
+            "description": "blog updated"
           }
         },
         "requestBody": {
@@ -294,7 +272,8 @@
                 "type": "file"
               }
             }
-          }
+          },
+          "required": true
         }
       }
     }
@@ -377,7 +356,8 @@
   "components": {
     "securitySchemes": {
       "basic_auth": {
-        "type": "basic"
+        "type": "http",
+        "scheme": "basic"
       },
       "api_key": {
         "type": "apiKey",

test-app/swagger/v3/openapi.json

@@ -0,0 +1,160 @@
+{
+  "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"
+          }
+        },
+        "parameters": [
+          {
+            "name": "a_param",
+            "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}": {
+      "get": {
+        "summary": "a summary",
+        "tags": [
+          "Parameter Serialization: Query String"
+        ],
+        "parameters": [
+          {
+            "name": "a_param",
+            "in": "path",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    }
+  },
+  "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": "http",
+        "scheme": "basic"
+      },
+      "api_key": {
+        "type": "apiKey",
+        "name": "api_key",
+        "in": "query"
+      }
+    }
+  }
+}