diff --git a/.ruby-version b/.ruby-version index 2bf1c1c..2714f53 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.3.1 +2.6.4 diff --git a/.travis.yml b/.travis.yml index bdf321a..304c64c 100644 --- 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: diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7f30a85 --- /dev/null +++ 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c22b355 --- /dev/null +++ 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. diff --git a/Gemfile b/Gemfile index 1abf797..c9d5c4e 100644 --- a/Gemfile +++ b/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', '~> 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' diff --git a/README.md b/README.md index 08f0157..3cfff07 100644 --- 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: + +``` + +| 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. @@ -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 ### diff --git a/rswag-api/rswag-api.gemspec b/rswag-api/rswag-api.gemspec index 299172d..3a14bb2 100644 --- 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 diff --git a/rswag-specs/lib/generators/rswag/specs/install/templates/swagger_helper.rb b/rswag-specs/lib/generators/rswag/specs/install/templates/swagger_helper.rb index 3d27729..3855920 100644 --- 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 diff --git a/rswag-specs/lib/rswag/specs/example_group_helpers.rb b/rswag-specs/lib/rswag/specs/example_group_helpers.rb index c293c63..4939abb 100644 --- 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) diff --git a/rswag-specs/lib/rswag/specs/response_validator.rb b/rswag-specs/lib/rswag/specs/response_validator.rb index 5b366ce..c3e363f 100644 --- 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 diff --git a/rswag-specs/rswag-specs.gemspec b/rswag-specs/rswag-specs.gemspec index 0e4686e..e3ddaf3 100644 --- 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 diff --git a/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb b/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb index 619a8d7..c870bfc 100644 --- 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 diff --git a/rswag-ui/package-lock.json b/rswag-ui/package-lock.json index 664d3fa..144573b 100644 --- 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==" } } } diff --git a/rswag-ui/package.json b/rswag-ui/package.json index 1fce627..27dbc6c 100644 --- 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" } } diff --git a/rswag-ui/rswag-ui.gemspec b/rswag-ui/rswag-ui.gemspec index 5b53548..1584470 100644 --- 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