Update changelog

Point the railtie to the correct file

.ruby-version

@@ -1 +1 @@
-2.3.1
+2.6.4

.travis.yml

@@ -1,24 +1,28 @@
 language: ruby
 
+dist: xenial
+services:
+  - xvfb
+
 rvm:
-  - 2.2.5
+  - 2.6.4
 
 env:
+  - RAILS_VERSION=6.0.0
   - RAILS_VERSION=5.2.0
-  - RAILS_VERSION=4.2.0
-  - RAILS_VERSION=3.2.22
+
+addons:
+  apt:
+    packages:
+      - libqtwebkit-dev
+      - libqtwebkit4
 
 cache:
   directories:
-    - /home/travis/.rvm/gems/ruby-2.2.5
+    - /home/travis/.rvm/gems/ruby-2.6.4
 
 install: ./ci/build.sh
 
-before_script:
-  - export DISPLAY=:99.0
-  - sh -e /etc/init.d/xvfb start
-  - sleep 3
-
 script: ./ci/test.sh
 
 jobs:
@@ -49,6 +53,7 @@ jobs:
         gemspec: rswag-ui.gemspec
         provider: rubygems
         api_key: $RUBYGEMS_API_KEY
+        skip_cleanup: true
         on:
           branch: master
           tags: true

CHANGELOG.md

@@ -0,0 +1,33 @@
+# 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).
+
+## [Unreleased]
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+## [2.1.1] - 2019-10-18
+### Fixed
+- Fix incorrect require reference for swagger_generator [#248](https://github.com/rswag/rswag/issues/248)
+
+## [2.1.0] - 2019-10-17
+### Added
+- New Spec Generator [#75](https://github.com/rswag/rswag/pull/75)
+- Support for Options and Trace verbs; You must use a framework that supports this, for Options Rails 6.1+ Rails 6 does not support Trace. [#237](https://github.com/rswag/rswag/pull/75)
+### Changed
+- Update swagger-ui to 3.18.2 [#240](https://github.com/rswag/rswag/pull/240)
+
+## [2.0.6] - 2019-10-03
+### Added
+- Support for Rails 6 [#228](https://github.com/rswag/rswag/pull/228)
+- Support for Windows paths [#176](https://github.com/rswag/rswag/pull/176)
+### Changed
+- Show response body when error code is not expected [#117](https://github.com/rswag/rswag/pull/177)
+
+## [2.0.5] - 2018-07-10

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+## Fork, then clone the repo:
+```
+git clone git@github.com:rswag/rswag.git
+cd rswag
+```
+
+## Build
+Set up your machine:
+```
+./ci/build.sh
+```
+Or manually
+```
+bundle
+cd test-app
+bundle exec rake db:setup
+cd -
+
+cd rswag-ui
+npm install
+cd -
+```
+
+## Test
+Make sure the tests pass:
+```
+./ci/test.sh
+```
+or manually
+```
+cd test-app
+bundle exec rspec
+```
+
+Make your change. Add tests for your change. Make the tests pass:
+
+```
+bundle exec rspec
+```
+
+Push to your fork and [submit a Pull Request][pr].
+
+[pr]: https://github.com/rswag/rswag/compare/
+
+## Release
+(for maintainers)
+
+Update the changelog.md, putting the new version number in and moving the Unreleased marker.
+
+Merge the changes into master you wish to release.
+
+Add and push a new git tag, annotated tags preferred:
+```
+git tag -s 2.0.6 -m 'v2.0.6'
+```
+
+Travis will detect the tag and release all gems with that tag version number.

Gemfile

@@ -9,11 +9,16 @@ gem 'rails', "#{rails_version}"
 case rails_version.split('.').first
 when '3'
   gem 'strong_parameters'
-when '4', '5'
+when '4', '5', '6'
   gem 'responders'
 end
 
-gem 'sqlite3'
+case rails_version.split('.').first
+when '3', '4', '5'
+  gem 'sqlite3', '~> 1.3.6'
+when  '6'
+  gem 'sqlite3', '~> 1.4.1'
+end
 
 gem 'rswag-api', path: './rswag-api'
 gem 'rswag-ui', path: './rswag-ui'

README.md

@@ -1,6 +1,6 @@
-rswag (formerly swagger_rails)
+rswag
 =========
-[![Build Status](https://travis-ci.org/domaindrivendev/rswag.svg?branch=master)](https://travis-ci.org/domaindrivendev/rswag)
+[![Build Status](https://travis-ci.org/rswag/rswag.svg?branch=master)](https://travis-ci.org/rswag/rswag)
 
 [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.
 
@@ -14,9 +14,9 @@ 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/domaindrivendev/rswag/tree/master)|2.0|3.13.2|
-|[2.0.0](https://github.com/domaindrivendev/rswag/tree/2.0.0)|2.0|3.13.2|
-|[1.6.0](https://github.com/domaindrivendev/rswag/tree/1.6.0)|2.0|2.2.5|
+|[master](https://github.com/rswag/rswag/tree/master)|2.0|3.18.2|
+|[2.0.6](https://github.com/rswag/rswag/tree/2.0.6)|2.0|3.17.3|
+|[1.6.0](https://github.com/rswag/rswag/tree/1.6.0)|2.0|2.2.5|
 
 ## Getting Started ##
 
@@ -33,7 +33,7 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
     gem 'rswag-api'
     gem 'rswag-ui'
 
-    groups :test do
+    group :test do
       gem 'rspec-rails'
       gem 'rswag-specs'
     end
@@ -44,6 +44,14 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
     ```ruby
     rails g rswag:install
     ```
+    
+    Or run the install generators for each package separately if you installed Rswag as separate gems, as indicated above:
+    
+    ```ruby
+    rails g rswag:api:install 
+    rails g rswag:ui:install
+    RAILS_ENV=test rails g rswag:specs:install
+    ```
 
 3. Create an integration spec to describe and test your API.
 
@@ -195,7 +203,8 @@ RSpec.configure do |config|
       swagger: '2.0',
       info: {
         title: 'API V1',
-        version: 'v1'
+        version: 'v1',
+        description: 'This is the first version of my API'
       },
       basePath: '/api/v1'
     },
@@ -204,7 +213,8 @@ RSpec.configure do |config|
       swagger: '2.0',
       info: {
         title: 'API V2',
-        version: 'v2'
+        version: 'v2',
+        description: 'This is the second version of my API'
       },
       basePath: '/api/v2'
     }
@@ -212,7 +222,8 @@ RSpec.configure do |config|
 end
 ```
 
-__NOTE__: By default, the paths, operations and responses defined in your spec files will be associated with the first Swagger document in _swagger_helper.rb_. If you're using multiple documents, you'll need to tag the individual specs with their target document name:
+#### Supporting multiple versions of API #### 
+By default, the paths, operations and responses defined in your spec files will be associated with the first Swagger document in _swagger_helper.rb_. If your API has multiple versions, you should be using separate documents to describe each of them. In order to assign a file with a given version of API, you'll need to add the ```swagger_doc``` tag to each spec specifying its target document name:
 
 ```ruby
 # spec/integration/v2/blogs_spec.rb
@@ -226,6 +237,25 @@ describe 'Blogs API', swagger_doc: 'v2/swagger.json' do
 end
 ```
 
+#### Formatting the description literals: #### 
+Swagger supports the Markdown syntax to format strings. This can be especially handy if you were to provide a long description of a given API version or endpoint. Use [this guide](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for reference. 
+
+__NOTE:__ There is one difference between the official Markdown syntax and Swagger interpretation, namely tables. To create a table like this:
+
+| Column1 | Collumn2 |
+| ------- | -------- |
+| cell1   | cell2    | 
+
+you should use the folowing syntax, making sure there are no whitespaces at the start of any of the lines:
+
+```
+
+| Column1 | Collumn2 |
+| ------- | -------- |
+| cell1   | cell2    |
+
+```
+
 ### 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 supports :basic, :apiKey and :oauth2 scheme types. See [the spec](http://swagger.io/specification/#security-definitions-object-109) for more info.
@@ -457,7 +487,7 @@ Rswag::Api.configure do |c|
 end
 ```
 
-Note how the filter is passed the rack env for the current request. This provides a lot of flexibilty. For example, you can assign the "host" property (as shown) or you could inspect session information or an Authoriation header and remove operations based on user permissions.
+Note how the filter is passed the rack env for the current request. This provides a lot of flexibilty. For example, you can assign the "host" property (as shown) or you could inspect session information or an Authorization header and remove operations based on user permissions.
 
 ### Enable Swagger Endpoints for swagger-ui ###
 
@@ -494,7 +524,7 @@ rails g rswag:ui:custom
 
 This will add a local version that you can modify at _app/views/rswag/ui/home/index.html.erb_
 
-### Publish UI Assets with "assets:precompile:
+### Serve UI Assets Directly from your Web Server
 
 Rswag ships with an embedded version of the [swagger-ui](https://github.com/swagger-api/swagger-ui), which is a static collection of JavaScript and CSS files. These assets are served by the rswag-ui middleware. However, for optimal performance you may want to serve them directly from your web server (e.g. Apache or NGINX). To do this, you'll need to copy them to the web server root. This is the "public" folder in a typical Rails application.
 

rswag-api/rswag-api.gemspec

@@ -13,5 +13,5 @@ Gem::Specification.new do |s|
 
   s.files = Dir["{lib}/**/*"] + ["MIT-LICENSE", "Rakefile"]
 
-  s.add_dependency 'railties', '>= 3.1', '< 6.0'
+  s.add_dependency 'railties', '>= 3.1', '< 6.1'
 end

rswag-specs/lib/generators/rspec/USAGE

@@ -0,0 +1,9 @@
+Description:
+    This creates an RSpec request spec to define Swagger documentation for a
+    controller. It will create a test for each of the controller's methods.
+
+Example:
+    rails generate rspec:swagger V3::AccountsController
+
+    This will create:
+        spec/requests/v3/accounts_spec.rb

rswag-specs/lib/generators/rspec/swagger_generator.rb

@@ -0,0 +1,22 @@
+require 'rswag/route_parser'
+require 'rails/generators'
+
+module Rspec
+  class SwaggerGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path('../templates', __FILE__)
+
+    def setup
+      @routes = Rswag::RouteParser.new(controller_path).routes
+    end
+
+    def create_spec_file
+      template 'spec.rb', File.join('spec', 'requests', "#{controller_path}_spec.rb")
+    end
+
+    private
+
+    def controller_path
+      file_path.chomp('_controller')
+    end
+  end
+end

rswag-specs/lib/generators/rspec/templates/spec.rb

@@ -0,0 +1,30 @@
+require 'swagger_helper'
+
+RSpec.describe '<%= controller_path %>', type: :request do
+<%   @routes.each do | template, path_item | %>
+  path '<%= template %>' do
+<%    unless path_item[:params].empty? -%>
+    # You'll want to customize the parameter types...
+<%       path_item[:params].each do |param| -%>
+    parameter name: '<%= param %>', in: :path, type: :string, description: '<%= param %>'
+<%      end -%>
+<%    end -%>
+<%    path_item[:actions].each do | action, details | %>
+    <%= action %>('<%= details[:summary] %>') do
+      response(200, 'successful') do
+<%      unless path_item[:params].empty? -%>
+<%        path_item[:params].each do |param| -%>
+        let(:<%= param %>) { '123' }
+<%        end -%>
+<%      end -%>
+
+        after do |example|
+          example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) }
+        end
+        run_test!
+      end
+    end
+<%     end -%>
+  end
+<%  end -%>
+end

rswag-specs/lib/generators/rswag/specs/install/templates/swagger_helper.rb

@@ -3,11 +3,11 @@ require 'rails_helper'
 RSpec.configure do |config|
   # Specify a root folder where Swagger JSON files are generated
   # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
-  # to ensure that it's confiugred to server Swagger from the same folder
-  config.swagger_root = Rails.root.to_s + '/swagger'
+  # to ensure that it's configured to serve Swagger from the same folder
+  config.swagger_root = Rails.root.join('swagger').to_s
 
   # Define one or more Swagger documents and provide global metadata for each one
-  # When you run the 'rswag:specs:to_swagger' rake task, the complete Swagger will
+  # When you run the 'rswag:specs:swaggerize' rake task, the complete Swagger will
   # be generated at the provided relative path under swagger_root
   # By default, the operations defined in spec files are added to the first
   # document below. You can override this behavior by adding a swagger_doc tag to the

rswag-specs/lib/rswag/route_parser.rb

@@ -0,0 +1,58 @@
+module Rswag
+  class RouteParser
+    attr_reader :controller
+
+    def initialize(controller)
+      @controller = controller
+    end
+
+    def routes
+      ::Rails.application.routes.routes.select do |route|
+        route.defaults[:controller] == controller
+      end.reduce({}) do |tree, route|
+        path = path_from(route)
+        verb = verb_from(route)
+        tree[path] ||= { params: params_from(route), actions: {} }
+        tree[path][:actions][verb] = { summary: summary_from(route) }
+        tree
+      end
+    end
+
+    private
+
+    def path_from(route)
+      route.path.spec.to_s
+        .chomp('(.:format)') # Ignore any format suffix
+        .gsub(/:([^\/.?]+)/, '{\1}') # Convert :id to {id}
+    end
+
+    def verb_from(route)
+      verb = route.verb
+      if verb.kind_of? String
+        verb.downcase
+      else
+        verb.source.gsub(/[$^]/, '').downcase
+      end
+    end
+
+    def summary_from(route)
+      verb = route.requirements[:action]
+      noun = route.requirements[:controller].split('/').last.singularize
+
+      # Apply a few customizations to make things more readable
+      case verb
+      when 'index'
+        verb = 'list'
+        noun = noun.pluralize
+      when 'destroy'
+        verb = 'delete'
+      end
+
+      "#{verb} #{noun}"
+    end
+
+    def params_from(route)
+      route.segments - ['format']
+    end
+  end
+end

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

@@ -7,7 +7,7 @@ module Rswag
         describe(template, metadata, &block)
       end
 
-      [ :get, :post, :patch, :put, :delete, :head ].each do |verb|
+      [ :get, :post, :patch, :put, :delete, :head, :options, :trace ].each do |verb|
         define_method(verb) do |summary, &block|
           api_metadata = { operation: { verb: verb, summary: summary } }
           describe(verb, api_metadata, &block)

rswag-specs/lib/rswag/specs/extended_schema.rb

@@ -3,7 +3,7 @@ require 'json-schema'
 module Rswag
   module Specs
     class ExtendedSchema < JSON::Schema::Draft4
-      
+
       def initialize
         super
         @attributes['type'] = ExtendedTypeAttribute
@@ -13,7 +13,7 @@ module Rswag
     end
 
     class ExtendedTypeAttribute < JSON::Schema::TypeV4Attribute
-      
+
       def self.validate(current_schema, data, fragments, processor, validator, options={})
         return if data.nil? && current_schema.schema['x-nullable'] == true
         super

rswag-specs/lib/rswag/specs/railtie.rb

@@ -5,6 +5,10 @@ module Rswag
       rake_tasks do
         load File.expand_path('../../../tasks/rswag-specs_tasks.rake', __FILE__)
       end
+
+      generators do
+        require 'generators/rspec/swagger_generator.rb'
+      end
     end
   end
 end

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

@@ -54,7 +54,7 @@ module Rswag
         definitions[key]
       end
 
-      def add_verb(request, metadata) 
+      def add_verb(request, metadata)
         request[:verb] = metadata[:operation][:verb]
       end
 
@@ -104,7 +104,7 @@ module Rswag
         end
 
         # Content-Type header
-        consumes = metadata[:operation][:consumes] || swagger_doc[:consumes] 
+        consumes = metadata[:operation][:consumes] || swagger_doc[:consumes]
         if consumes
           content_type = example.respond_to?(:'Content-Type') ? example.send(:'Content-Type') : consumes.first
           tuples << [ 'Content-Type', content_type ]

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

@@ -14,17 +14,19 @@ module Rswag
       def validate!(metadata, response)
         swagger_doc = @config.get_swagger_doc(metadata[:swagger_doc])
 
-        validate_code!(metadata, response.code)
+        validate_code!(metadata, response)
         validate_headers!(metadata, response.headers)
         validate_body!(metadata, swagger_doc, response.body)
       end
 
       private
 
-      def validate_code!(metadata, code)
+      def validate_code!(metadata, response)
         expected = metadata[:response][:code].to_s
-        if code != expected
-          raise UnexpectedResponse, "Expected response code '#{code}' to match '#{expected}'"
+        if response.code != expected
+          raise UnexpectedResponse,
+                "Expected response code '#{response.code}' to match '#{expected}'\n" \
+                "Response body: #{response.body}"
         end
       end
 

rswag-specs/rswag-specs.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
 
   s.files = Dir["{lib}/**/*"] + ["MIT-LICENSE", "Rakefile" ]
 
-  s.add_dependency 'activesupport', '>= 3.1', '< 6.0'
-  s.add_dependency 'railties', '>= 3.1', '< 6.0'
+  s.add_dependency 'activesupport', '>= 3.1', '< 6.1'
+  s.add_dependency 'railties', '>= 3.1', '< 6.1'
   s.add_dependency 'json-schema', '~> 2.2'
 end

rswag-specs/spec/generators/rspec/swagger_generator_spec.rb

@@ -0,0 +1,44 @@
+require 'generator_spec'
+require 'generators/rspec/swagger_generator'
+require 'tmpdir'
+
+module Rspec
+  describe SwaggerGenerator do
+    include GeneratorSpec::TestCase
+    destination Dir.mktmpdir
+
+    before(:all) do
+      prepare_destination
+      fixtures_dir = File.expand_path('../fixtures', __FILE__)
+      FileUtils.cp_r("#{fixtures_dir}/spec", destination_root)
+    end
+
+    after(:all) do
+
+    end
+
+    it 'installs the swagger_helper for rspec' do
+      allow_any_instance_of(Rswag::RouteParser).to receive(:routes).and_return(fake_routes)
+      run_generator ['Posts::CommentsController']
+
+      assert_file('spec/requests/posts/comments_spec.rb') do |content|
+        assert_match(/parameter name: 'post_id', in: :path, type: :string/, content)
+        assert_match(/patch\('update_comments comment'\)/, content)
+      end
+    end
+
+    private
+
+    def fake_routes
+      {
+        "/posts/{post_id}/comments/{id}" => {
+          :params => ["post_id", "id"],
+          :actions => {
+            "get" => { :summary=>"show comment" },
+            "patch" => { :summary=>"update_comments comment" }
+          }
+        }
+      }
+    end
+  end
+end

rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb

@@ -24,7 +24,7 @@ module Rswag
         end
       end
 
-      describe '#get|post|patch|put|delete|head(verb, summary)' do
+      describe '#get|post|patch|put|delete|head|options|trace(verb, summary)' do
         before { subject.post('Creates a blog') }
 
         it "delegates to 'describe' with 'operation' metadata" do

rswag-ui/package-lock.json

@@ -5,9 +5,9 @@
   "requires": true,
   "dependencies": {
     "swagger-ui-dist": {
-      "version": "3.13.2",
-      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.13.2.tgz",
-      "integrity": "sha1-EL9SK9J0q2SU0r0Nuvn+2ibbHKI="
+      "version": "3.18.2",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.18.2.tgz",
+      "integrity": "sha512-pWAEiKkgWUJvjmLW9AojudnutJ+NTn5g6OdNLj1iIJWwCkoy40K3Upwa24DqFbmIE4vLX4XplND61hp2L+s5vg=="
     }
   }
 }

rswag-ui/package.json

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

rswag-ui/rswag-ui.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |s|
   s.description = "Expose beautiful API documentation, that's powered by Swagger JSON endpoints, including a UI to explore and test operations"
   s.license     = "MIT"
 
-  s.files = Dir["{lib,node_modules}/**/*"] + ["MIT-LICENSE", "Rakefile" ]
+  s.files = Dir.glob("{lib,node_modules}/**/*") + ["MIT-LICENSE", "Rakefile" ]
 
-  s.add_dependency 'actionpack', '>=3.1', '< 6.0'
-  s.add_dependency 'railties', '>= 3.1', '< 6.0'
+  s.add_dependency 'actionpack', '>=3.1', '< 6.1'
+  s.add_dependency 'railties', '>= 3.1', '< 6.1'
 end

test-app/app/assets/config/manifest.js

@@ -0,0 +1,2 @@
+//= link_tree ../images
+//= link_directory ../stylesheets .css

test-app/spec/swagger_helper.rb

@@ -3,7 +3,7 @@ require 'rails_helper'
 RSpec.configure do |config|
   # Specify a root folder where Swagger JSON files are generated
   # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
-  # to ensure that it's confiugred to server Swagger from the same folder
+  # to ensure that it's configured to serve Swagger from the same folder
   config.swagger_root = Rails.root.to_s + '/swagger'
 
   # Define one or more Swagger documents and provide global metadata for each one