Merge branch 'master' into allow-yaml-parsing-in-rswag-api

2026-01-22 22:06:43 +00:00 · 2019-10-14 21:41:18 +01:00 · 2019-10-14 21:41:18 +01:00 · 69edcd1be6
commit 69edcd1be6
parent 9eb2d3ddec b41d4e1276
15 changed files with 155 additions and 36 deletions
--- a/.ruby-version
+++ b/.ruby-version
@ -1 +1 @@
-2.3.1
+2.6.4
--- a/.travis.yml
+++ b/.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:
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -0,0 +1,27 @@
+# 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
+- Update swagger-ui to 3.18.2
+### 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
--- a/CONTRIBUTING.md
+++ b/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.
--- a/9
+++ b/9
@ -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', '~> 1.3.6'
+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'
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 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.17.3|
-|[2.0.5](https://github.com/domaindrivendev/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|
+|[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 ##

@ -202,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'
    },
@ -211,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'
    }
@ -219,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
@ -233,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:
+
+```
+&#13;
+| Column1 | Collumn2 |&#13;
+| ------- | -------- |&#13;
+| cell1   | cell2    |&#13;
+&#13;
+```
+
 ### 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.
@ -464,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 ###

--- a/rswag-api/rswag-api.gemspec
+++ b/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
--- a/rswag-specs/lib/generators/rswag/specs/install/templates/swagger_helper.rb
+++ b/rswag-specs/lib/generators/rswag/specs/install/templates/swagger_helper.rb
@ -4,7 +4,7 @@ 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 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:swaggerize' rake task, the complete Swagger will
--- a/rswag-specs/lib/rswag/specs/example_group_helpers.rb
+++ b/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)
--- a/rswag-specs/lib/rswag/specs/response_validator.rb
+++ b/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

--- a/rswag-specs/rswag-specs.gemspec
+++ b/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
--- a/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb
+++ b/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
--- a/rswag-ui/package-lock.json
+++ b/rswag-ui/package-lock.json
@ -5,9 +5,9 @@
  "requires": true,
  "dependencies": {
    "swagger-ui-dist": {
-      "version": "3.17.3",
-      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.17.3.tgz",
-      "integrity": "sha1-37lkCMzEZ3UVX3NpGQxdSyAW/lw="
+      "version": "3.18.2",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.18.2.tgz",
+      "integrity": "sha512-pWAEiKkgWUJvjmLW9AojudnutJ+NTn5g6OdNLj1iIJWwCkoy40K3Upwa24DqFbmIE4vLX4XplND61hp2L+s5vg=="
    }
  }
 }
--- a/rswag-ui/package.json
+++ b/rswag-ui/package.json
@ -3,6 +3,6 @@
  "version": "1.0.0",
  "private": true,
  "dependencies": {
-    "swagger-ui-dist": "3.17.3"
+    "swagger-ui-dist": "3.18.2"
  }
 }
--- a/rswag-ui/rswag-ui.gemspec
+++ b/rswag-ui/rswag-ui.gemspec
@ -13,6 +13,6 @@ Gem::Specification.new do |s|

  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
 @ -1 +1 @@
 .3.1
 .6.4