Merge pull request #235 from BookOfGreg/doc/update-contrib

Update contributing instructions. Add changelog

.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:
@@ -44,13 +48,12 @@ jobs:
           tags: true
 
     - stage: publish components
-      script:
+      script: 'cd rswag-ui'
-        - 'cd rswag-ui'
-        - 'npm install'
       deploy:
         gemspec: rswag-ui.gemspec
         provider: rubygems
         api_key: $RUBYGEMS_API_KEY
+        skip_cleanup: true
         on:
           branch: master
           tags: true

CHANGELOG.md

@@ -0,0 +1,26 @@
+# 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.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)
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+## [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|
+|[master](https://github.com/rswag/rswag/tree/master)|2.0|3.17.3|
-|[2.0.0](https://github.com/domaindrivendev/rswag/tree/2.0.0)|2.0|3.13.2|
+|[2.0.5](https://github.com/rswag/rswag/tree/2.0.4)|2.0|3.17.3|
-|[1.6.0](https://github.com/domaindrivendev/rswag/tree/1.6.0)|2.0|2.2.5|
+|[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,13 @@ 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 rswag:ui:install
+    RAILS_ENV=test rails g rswag:specs:install
+    ```
 
 3. Create an integration spec to describe and test your API.
 
@@ -195,7 +202,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 +212,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 +221,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 +236,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 +486,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 ###
 

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/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
+  # to ensure that it's configured to serve Swagger from the same folder
-  config.swagger_root = Rails.root.to_s + '/swagger'
+  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/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
+        if response.code != expected
-          raise UnexpectedResponse, "Expected response code '#{code}' to match '#{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 'activesupport', '>= 3.1', '< 6.1'
-  s.add_dependency 'railties', '>= 3.1', '< 6.0'
+  s.add_dependency 'railties', '>= 3.1', '< 6.1'
   s.add_dependency 'json-schema', '~> 2.2'
 end

rswag-ui/package-lock.json

@@ -5,9 +5,9 @@
   "requires": true,
   "dependencies": {
     "swagger-ui-dist": {
-      "version": "3.13.2",
+      "version": "3.17.3",
-      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.13.2.tgz",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.17.3.tgz",
-      "integrity": "sha1-EL9SK9J0q2SU0r0Nuvn+2ibbHKI="
+      "integrity": "sha1-37lkCMzEZ3UVX3NpGQxdSyAW/lw="
     }
   }
 }

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.17.3"
   }
 }

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 'actionpack', '>=3.1', '< 6.1'
-  s.add_dependency 'railties', '>= 3.1', '< 6.0'
+  s.add_dependency 'railties', '>= 3.1', '< 6.1'
 end

test-app/db/schema.rb

@@ -2,15 +2,15 @@
 # of editing this file, please use the migrations feature of Active Record to
 # incrementally modify your database, and then regenerate this schema definition.
 #
-# Note that this schema.rb definition is the authoritative source for your
+# This file is the source Rails uses to define your schema when running `rails
-# database schema. If you need to create the application database on another
+# db:schema:load`. When creating a new database, `rails db:schema:load` tends to
-# system, you should be using db:schema:load, not running all the migrations
+# be faster and is potentially less error prone than running all of your
-# from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# migrations from scratch. Old migrations may fail to apply correctly if those
-# you'll amass, the slower it'll run and the greater likelihood for issues).
+# migrations use external dependencies or application code.
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 20160218212104) do
+ActiveRecord::Schema.define(version: 2016_02_18_212104) do
 
   create_table "blogs", force: :cascade do |t|
     t.string "title"

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