From 4842055ee69d9043132ff7f6702ed23130de5663 Mon Sep 17 00:00:00 2001 From: andrew morton Date: Tue, 13 Sep 2016 06:43:39 -0600 Subject: [PATCH 01/83] Add a contributing file The exact sequence of commands to be able to run the tests wasn't obvious to me so I'm assumiing others could use a hand. I used the factory_girl_rails gem's file as a starting point. --- CONTRIBUTING.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..618eda5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing + +Fork, then clone the repo: + +``` +git clone git@github.com:your-username/swagger_rails.git +cd swagger_rails +``` + +Set up your machine: + +``` +bundle +cd spec/dummy +bundle exec rake db:setup +cd - +``` + +Make sure the tests pass: + +``` +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/domaindrivendev/swagger_rails/compare/ From c9bda862b62f4abcba892c3872ef66af8b9d6c05 Mon Sep 17 00:00:00 2001 From: Paul Carey Date: Thu, 6 Jul 2017 10:43:59 +0100 Subject: [PATCH 02/83] adds request spec generator shamelessly stollen from rspec-rails-swagger --- .gitignore | 1 + .../lib/generators/rspec/swagger/USAGE | 9 +++ .../rspec/swagger/swagger_generator.rb | 24 +++++++ .../rspec/swagger/templates/spec.rb | 30 +++++++++ .../lib/rspec/rails/swagger/route_parser.rb | 62 +++++++++++++++++++ rswag-specs/lib/rswag/specs/railtie.rb | 4 ++ 6 files changed, 130 insertions(+) create mode 100644 rswag-specs/lib/generators/rspec/swagger/USAGE create mode 100644 rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb create mode 100644 rswag-specs/lib/generators/rspec/swagger/templates/spec.rb create mode 100644 rswag-specs/lib/rspec/rails/swagger/route_parser.rb diff --git a/.gitignore b/.gitignore index d688e03..a96771f 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ **/*/*.sqlite3 **/*/public/assets *.swp +.idea diff --git a/rswag-specs/lib/generators/rspec/swagger/USAGE b/rswag-specs/lib/generators/rspec/swagger/USAGE new file mode 100644 index 0000000..bc354c4 --- /dev/null +++ b/rswag-specs/lib/generators/rspec/swagger/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 diff --git a/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb b/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb new file mode 100644 index 0000000..48f92aa --- /dev/null +++ b/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb @@ -0,0 +1,24 @@ +require 'rspec/rails/swagger/route_parser' +require 'rails/generators' + +module Rspec + module Generators + class SwaggerGenerator < ::Rails::Generators::NamedBase + source_root File.expand_path('../templates', __FILE__) + + def setup + @routes = RSpec::Rails::Swagger::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 +end diff --git a/rswag-specs/lib/generators/rspec/swagger/templates/spec.rb b/rswag-specs/lib/generators/rspec/swagger/templates/spec.rb new file mode 100644 index 0000000..75ff7b3 --- /dev/null +++ b/rswag-specs/lib/generators/rspec/swagger/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 '<%= param %>', in: :body, type: :string + <% 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 diff --git a/rswag-specs/lib/rspec/rails/swagger/route_parser.rb b/rswag-specs/lib/rspec/rails/swagger/route_parser.rb new file mode 100644 index 0000000..9ab9513 --- /dev/null +++ b/rswag-specs/lib/rspec/rails/swagger/route_parser.rb @@ -0,0 +1,62 @@ +module RSpec + module Rails + module Swagger + 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 + end +end diff --git a/rswag-specs/lib/rswag/specs/railtie.rb b/rswag-specs/lib/rswag/specs/railtie.rb index 8deec2b..43e2302 100644 --- a/rswag-specs/lib/rswag/specs/railtie.rb +++ b/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/swagger_generator.rb' + end end end end From 3eda72155a368edd9273f46638a5824cc4666114 Mon Sep 17 00:00:00 2001 From: Tomasz Czernuszenko Date: Mon, 7 Aug 2017 14:12:40 +0100 Subject: [PATCH 03/83] Updated Readme.md: Added a section on markdown formatting and and clarified some descriptions of API versioning --- README.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 63ed64a..4c1dce4 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,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' }, @@ -183,7 +184,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' } @@ -191,7 +193,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 @@ -205,6 +208,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. From b0712418a31f4dab5c115a0f4e21f39ca29e476d Mon Sep 17 00:00:00 2001 From: Austin Kabiru Date: Fri, 30 Nov 2018 12:33:13 +0300 Subject: [PATCH 04/83] feat(auth): Allow Basic auth to be enabled --- .../lib/generators/rswag/ui/install/templates/rswag-ui.rb | 4 ++++ rswag-ui/lib/rswag/ui/configuration.rb | 8 ++++++++ rswag-ui/lib/rswag/ui/engine.rb | 7 +++++++ 3 files changed, 19 insertions(+) diff --git a/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb b/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb index 084a512..b39e2f9 100644 --- a/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb +++ b/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb @@ -7,4 +7,8 @@ Rswag::Ui.configure do |c| # then the list below should correspond to the relative paths for those endpoints c.swagger_endpoint '/api-docs/v1/swagger.json', 'API V1 Docs' + + # Add Basic Auth in case your API is private + # c.basic_auth_enabled = true + # c.basic_auth_credentials 'username', 'password' end diff --git a/rswag-ui/lib/rswag/ui/configuration.rb b/rswag-ui/lib/rswag/ui/configuration.rb index 5f33c2c..ae06434 100644 --- a/rswag-ui/lib/rswag/ui/configuration.rb +++ b/rswag-ui/lib/rswag/ui/configuration.rb @@ -4,6 +4,7 @@ module Rswag module Ui class Configuration attr_reader :template_locations + attr_accessor :basic_auth_enabled attr_accessor :config_object attr_accessor :oauth_config_object attr_reader :assets_root @@ -20,6 +21,7 @@ module Rswag @assets_root = File.expand_path('../../../../node_modules/swagger-ui-dist', __FILE__) @config_object = {} @oauth_config_object = {} + @basic_auth_enabled = false end def swagger_endpoint(url, name) @@ -27,9 +29,15 @@ module Rswag @config_object[:urls] << { url: url, name: name } end + def basic_auth_credentials(username, password) + @config_object[:basic_auth] = { username: username, password: password } + end + + # rubocop:disable Naming/AccessorMethodName def get_binding binding end + # rubocop:enable Naming/AccessorMethodName end end end diff --git a/rswag-ui/lib/rswag/ui/engine.rb b/rswag-ui/lib/rswag/ui/engine.rb index 78ee075..2e157e3 100644 --- a/rswag-ui/lib/rswag/ui/engine.rb +++ b/rswag-ui/lib/rswag/ui/engine.rb @@ -7,6 +7,13 @@ module Rswag initializer 'rswag-ui.initialize' do |app| middleware.use Rswag::Ui::Middleware, Rswag::Ui.config + + if Rswag::Ui.config.basic_auth_enabled + c = Rswag::Ui.config + app.middleware.use ::Rack::Auth::Basic do |username, password| + c.config_object[:basic_auth].values == [username, password] + end + end end rake_tasks do From 875bbfa04b70aa5f80eef5cb36a774893d511c7c Mon Sep 17 00:00:00 2001 From: Austin Kabiru Date: Fri, 30 Nov 2018 14:23:11 +0300 Subject: [PATCH 05/83] chore(auth): Add documentation and specs --- README.md | 15 +++++- rswag-ui/spec/rswag/ui/configuration_spec.rb | 50 ++++++++++++++++++++ rswag-ui/spec/spec_helper.rb | 16 +++++++ 3 files changed, 79 insertions(+), 2 deletions(-) create mode 100644 rswag-ui/spec/rswag/ui/configuration_spec.rb diff --git a/README.md b/README.md index 08f0157..80b0d41 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,9 @@ 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 @@ -477,6 +477,17 @@ Rswag::Ui.configure do |c| end ``` +### Enable Simple Basic Auth for swagger-ui + +You can also update the _rswag-ui.rb_ initializer, installed with rswag-ui to specify a username and password should you want to keep your documentation private. + +```ruby +Rswag::Ui.configure do |c| + c.basic_auth_enabled = true + c.basic_auth_credentials 'username', 'password' +end +``` + ### Route Prefix for the swagger-ui ### Similar to rswag-api, you can customize the swagger-ui path by changing it's mount prefix in _routes.rb_: diff --git a/rswag-ui/spec/rswag/ui/configuration_spec.rb b/rswag-ui/spec/rswag/ui/configuration_spec.rb new file mode 100644 index 0000000..2df2c8d --- /dev/null +++ b/rswag-ui/spec/rswag/ui/configuration_spec.rb @@ -0,0 +1,50 @@ +require 'spec_helper' + +RSpec.describe Rswag::Ui::Configuration do + describe '#swagger_endpoints' + + describe '#basic_auth_enabled' do + context 'when unspecified' do + it 'defaults to false' do + configuration = described_class.new + basic_auth_enabled = configuration.basic_auth_enabled + + expect(basic_auth_enabled).to be(false) + end + end + + context 'when specified' do + context 'when set to true' do + it 'returns true' do + configuration = described_class.new + configuration.basic_auth_enabled = true + basic_auth_enabled = configuration.basic_auth_enabled + + expect(basic_auth_enabled).to be(true) + end + end + + context 'when set to false' do + it 'returns false' do + configuration = described_class.new + configuration.basic_auth_enabled = false + basic_auth_enabled = configuration.basic_auth_enabled + + expect(basic_auth_enabled).to be(false) + end + end + end + end + + describe '#basic_auth_credentials' do + it 'sets the username and password' do + configuration = described_class.new + configuration.basic_auth_credentials 'foo', 'bar' + credentials = configuration.config_object[:basic_aut] + + expect(credentials).to eq(username: 'foo', password: 'bar') + end + end + + describe '#get_binding' +end diff --git a/rswag-ui/spec/spec_helper.rb b/rswag-ui/spec/spec_helper.rb index e69de29..c242286 100644 --- a/rswag-ui/spec/spec_helper.rb +++ b/rswag-ui/spec/spec_helper.rb @@ -0,0 +1,16 @@ +require 'bundler/setup' + +require 'rack' +require 'rswag/ui/configuration' + +RSpec.configure do |config| + # Enable flags like --only-failures and --next-failure + config.example_status_persistence_file_path = ".rspec_status" + + # Disable RSpec exposing methods globally on `Module` and `main` + config.disable_monkey_patching! + + config.expect_with :rspec do |c| + c.syntax = :expect + end +end From 529cfae73e87403110e59a160a93a46d29bbe97f Mon Sep 17 00:00:00 2001 From: Austin Kabiru Date: Mon, 3 Dec 2018 11:02:57 +0300 Subject: [PATCH 06/83] fix: Scope auth to swagger endpoints --- rswag-ui/lib/rswag/ui/configuration.rb | 1 + rswag-ui/lib/rswag/ui/engine.rb | 26 ++++- rswag-ui/spec/rswag/ui/configuration_spec.rb | 6 +- rswag-ui/spec/spec_helper.rb | 104 +++++++++++++++++-- 4 files changed, 124 insertions(+), 13 deletions(-) diff --git a/rswag-ui/lib/rswag/ui/configuration.rb b/rswag-ui/lib/rswag/ui/configuration.rb index ae06434..ad46a49 100644 --- a/rswag-ui/lib/rswag/ui/configuration.rb +++ b/rswag-ui/lib/rswag/ui/configuration.rb @@ -1,4 +1,5 @@ require 'ostruct' +require 'rack' module Rswag module Ui diff --git a/rswag-ui/lib/rswag/ui/engine.rb b/rswag-ui/lib/rswag/ui/engine.rb index 2e157e3..962dc9f 100644 --- a/rswag-ui/lib/rswag/ui/engine.rb +++ b/rswag-ui/lib/rswag/ui/engine.rb @@ -1,5 +1,29 @@ require 'rswag/ui/middleware' +class UiBasicAuth < ::Rack::Auth::Basic + def call(env) + return @app.call(env) unless env_matching_path + + super(env) + end + + private + + def env_matching_path + swagger_endpoints = Rswag::Ui.config.swagger_endpoints[:urls] + swagger_endpoints.find do |endpoint| + base_path = base_path(endpoint[:url]) + env_base_path = base_path(env['PATH_INFO']) + + base_path == env_base_path + end + end + + def base_path(url) + url.downcase.split('/')[1] + end +end + module Rswag module Ui class Engine < ::Rails::Engine @@ -10,7 +34,7 @@ module Rswag if Rswag::Ui.config.basic_auth_enabled c = Rswag::Ui.config - app.middleware.use ::Rack::Auth::Basic do |username, password| + app.middleware.use UiBasicAuth do |username, password| c.config_object[:basic_auth].values == [username, password] end end diff --git a/rswag-ui/spec/rswag/ui/configuration_spec.rb b/rswag-ui/spec/rswag/ui/configuration_spec.rb index 2df2c8d..6e32590 100644 --- a/rswag-ui/spec/rswag/ui/configuration_spec.rb +++ b/rswag-ui/spec/rswag/ui/configuration_spec.rb @@ -1,4 +1,6 @@ -require 'spec_helper' +require 'rswag/ui/configuration' + +require_relative '../../spec_helper' RSpec.describe Rswag::Ui::Configuration do describe '#swagger_endpoints' @@ -40,7 +42,7 @@ RSpec.describe Rswag::Ui::Configuration do it 'sets the username and password' do configuration = described_class.new configuration.basic_auth_credentials 'foo', 'bar' - credentials = configuration.config_object[:basic_aut] + credentials = configuration.config_object[:basic_auth] expect(credentials).to eq(username: 'foo', password: 'bar') end diff --git a/rswag-ui/spec/spec_helper.rb b/rswag-ui/spec/spec_helper.rb index c242286..251aa51 100644 --- a/rswag-ui/spec/spec_helper.rb +++ b/rswag-ui/spec/spec_helper.rb @@ -1,16 +1,100 @@ -require 'bundler/setup' - -require 'rack' -require 'rswag/ui/configuration' - +# This file was generated by the `rspec --init` command. Conventionally, all +# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`. +# The generated `.rspec` file contains `--require spec_helper` which will cause +# this file to always be loaded, without a need to explicitly require it in any +# files. +# +# Given that it is always loaded, you are encouraged to keep this file as +# light-weight as possible. Requiring heavyweight dependencies from this file +# will add to the boot time of your test suite on EVERY test run, even for an +# individual file that may not need all of that loaded. Instead, consider making +# a separate helper file that requires the additional dependencies and performs +# the additional setup, and require it from the spec files that actually need +# it. +# +# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration RSpec.configure do |config| - # Enable flags like --only-failures and --next-failure - config.example_status_persistence_file_path = ".rspec_status" + # rspec-expectations config goes here. You can use an alternate + # assertion/expectation library such as wrong or the stdlib/minitest + # assertions if you prefer. + config.expect_with :rspec do |expectations| + # This option will default to `true` in RSpec 4. It makes the `description` + # and `failure_message` of custom matchers include text for helper methods + # defined using `chain`, e.g.: + # be_bigger_than(2).and_smaller_than(4).description + # # => "be bigger than 2 and smaller than 4" + # ...rather than: + # # => "be bigger than 2" + expectations.include_chain_clauses_in_custom_matcher_descriptions = true + end - # Disable RSpec exposing methods globally on `Module` and `main` + # rspec-mocks config goes here. You can use an alternate test double + # library (such as bogus or mocha) by changing the `mock_with` option here. + config.mock_with :rspec do |mocks| + # Prevents you from mocking or stubbing a method that does not exist on + # a real object. This is generally recommended, and will default to + # `true` in RSpec 4. + mocks.verify_partial_doubles = true + end + + # This option will default to `:apply_to_host_groups` in RSpec 4 (and will + # have no way to turn it off -- the option exists only for backwards + # compatibility in RSpec 3). It causes shared context metadata to be + # inherited by the metadata hash of host groups and examples, rather than + # triggering implicit auto-inclusion in groups with matching metadata. + config.shared_context_metadata_behavior = :apply_to_host_groups + +# The settings below are suggested to provide a good initial experience +# with RSpec, but feel free to customize to your heart's content. +=begin + # This allows you to limit a spec run to individual examples or groups + # you care about by tagging them with `:focus` metadata. When nothing + # is tagged with `:focus`, all examples get run. RSpec also provides + # aliases for `it`, `describe`, and `context` that include `:focus` + # metadata: `fit`, `fdescribe` and `fcontext`, respectively. + config.filter_run_when_matching :focus + + # Allows RSpec to persist some state between runs in order to support + # the `--only-failures` and `--next-failure` CLI options. We recommend + # you configure your source control system to ignore this file. + config.example_status_persistence_file_path = "spec/examples.txt" + + # Limits the available syntax to the non-monkey patched syntax that is + # recommended. For more details, see: + # - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/ + # - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/ + # - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode config.disable_monkey_patching! - config.expect_with :rspec do |c| - c.syntax = :expect + # This setting enables warnings. It's recommended, but in some cases may + # be too noisy due to issues in dependencies. + config.warnings = true + + # Many RSpec users commonly either run the entire suite or an individual + # file, and it's useful to allow more verbose output when running an + # individual spec file. + if config.files_to_run.one? + # Use the documentation formatter for detailed output, + # unless a formatter has already been configured + # (e.g. via a command-line flag). + config.default_formatter = "doc" end + + # Print the 10 slowest examples and example groups at the + # end of the spec run, to help surface which specs are running + # particularly slow. + config.profile_examples = 10 + + # Run specs in random order to surface order dependencies. If you find an + # order dependency and want to debug it, you can fix the order by providing + # the seed, which is printed after each run. + # --seed 1234 + config.order = :random + + # Seed global randomization in this process using the `--seed` CLI option. + # Setting this allows you to use `--seed` to deterministically reproduce + # test failures related to randomization by passing the same `--seed` value + # as the one that triggered the failure. + Kernel.srand config.seed +=end end From 9642937ee25f224888d04eabee39c607e1abc837 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Tue, 18 Dec 2018 13:29:40 +0000 Subject: [PATCH 07/83] Update swagger_helper.rb Use standard filesystem helpers to avoid OS specific slash errors. --- .../generators/rswag/specs/install/templates/swagger_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From e381bf85d4e927474777a0ad48228b85a954678c Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Sat, 22 Dec 2018 15:20:38 +0700 Subject: [PATCH 08/83] Show response body when the response code is unexpected. Makes it much easier to debug test failures --- rswag-specs/lib/rswag/specs/response_validator.rb | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) 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 From bfd3d66ec24d295e2bc765bcb73693a14134cc3b Mon Sep 17 00:00:00 2001 From: Rich Daley Date: Mon, 7 Jan 2019 14:09:50 +0000 Subject: [PATCH 09/83] Add a 'rake rswag' that runs swaggerize as the default --- README.md | 2 ++ rswag-specs/lib/tasks/rswag-specs_tasks.rake | 3 +++ 2 files changed, 5 insertions(+) diff --git a/README.md b/README.md index 08f0157..48fd461 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,8 @@ Once you have an API that can describe itself in Swagger, you've opened the trea rake rswag:specs:swaggerize ``` + This common command is also aliased as `rake rswag`. + 5. Spin up your app and check out the awesome, auto-generated docs at _/api-docs_! ## The rspec DSL ## diff --git a/rswag-specs/lib/tasks/rswag-specs_tasks.rake b/rswag-specs/lib/tasks/rswag-specs_tasks.rake index adc128c..b7d276b 100644 --- a/rswag-specs/lib/tasks/rswag-specs_tasks.rake +++ b/rswag-specs/lib/tasks/rswag-specs_tasks.rake @@ -16,3 +16,6 @@ namespace :rswag do end end end + +task :rswag => ['rswag:specs:swaggerize'] + From 29c9f7cae266daa6d87c3a43fdd831ffcc373d46 Mon Sep 17 00:00:00 2001 From: Ben Lewis Date: Wed, 6 Feb 2019 11:43:02 +0000 Subject: [PATCH 10/83] Allow parsing of yml swagger files in rswag-api --- rswag-api/lib/rswag/api/middleware.rb | 15 ++++++++++++++- .../rswag/api/fixtures/swagger/v1/swagger.yml | 5 +++++ rswag-api/spec/rswag/api/middleware_spec.rb | 15 +++++++++++++++ 3 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 rswag-api/spec/rswag/api/fixtures/swagger/v1/swagger.yml diff --git a/rswag-api/lib/rswag/api/middleware.rb b/rswag-api/lib/rswag/api/middleware.rb index 118c987..c1a4fbb 100644 --- a/rswag-api/lib/rswag/api/middleware.rb +++ b/rswag-api/lib/rswag/api/middleware.rb @@ -1,4 +1,5 @@ require 'json' +require 'yaml' module Rswag module Api @@ -14,7 +15,7 @@ module Rswag filename = "#{@config.resolve_swagger_root(env)}/#{path}" if env['REQUEST_METHOD'] == 'GET' && File.file?(filename) - swagger = load_json(filename) + swagger = parse_file(filename) @config.swagger_filter.call(swagger, env) unless @config.swagger_filter.nil? return [ @@ -29,6 +30,18 @@ module Rswag private + def parse_file(filename) + if /\.yml$/ === filename + load_yaml(filename) + else + load_json(filename) + end + end + + def load_yaml(filename) + YAML.safe_load(File.read(filename)) + end + def load_json(filename) JSON.parse(File.read(filename)) end diff --git a/rswag-api/spec/rswag/api/fixtures/swagger/v1/swagger.yml b/rswag-api/spec/rswag/api/fixtures/swagger/v1/swagger.yml new file mode 100644 index 0000000..0757e2a --- /dev/null +++ b/rswag-api/spec/rswag/api/fixtures/swagger/v1/swagger.yml @@ -0,0 +1,5 @@ +swagger: '2.0' +info: + title: API V1 + version: v1 +paths: {} diff --git a/rswag-api/spec/rswag/api/middleware_spec.rb b/rswag-api/spec/rswag/api/middleware_spec.rb index aaa148b..f784f25 100644 --- a/rswag-api/spec/rswag/api/middleware_spec.rb +++ b/rswag-api/spec/rswag/api/middleware_spec.rb @@ -76,6 +76,21 @@ module Rswag expect(response[2].join).to include('"host":"tempuri.org"') end end + + context 'when a path maps to a yaml swagger file' do + let(:env) { env_defaults.merge('PATH_INFO' => 'v1/swagger.yml') } + + it 'returns a 200 status' do + expect(response.length).to eql(3) + expect(response.first).to eql('200') + end + + it 'returns contents of the swagger file' do + expect(response.length).to eql(3) + expect(response[1]).to include( 'Content-Type' => 'application/json') + expect(response[2].join).to include('"title":"API V1"') + end + end end end end From 51b47f32e836433031585d1dee1536e38cb425ae Mon Sep 17 00:00:00 2001 From: Ben Lewis Date: Wed, 6 Feb 2019 12:15:01 +0000 Subject: [PATCH 11/83] version compatibility --- Gemfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index bbd3d73..1abf797 100644 --- a/Gemfile +++ b/Gemfile @@ -13,7 +13,7 @@ when '4', '5' gem 'responders' end -gem 'sqlite3' +gem 'sqlite3', '~> 1.3.6' gem 'rswag-api', path: './rswag-api' gem 'rswag-ui', path: './rswag-ui' From 9eb2d3ddec74fced2a2bff47dd652112a5480b35 Mon Sep 17 00:00:00 2001 From: Ben Lewis Date: Tue, 12 Feb 2019 10:47:15 +0000 Subject: [PATCH 12/83] Allow ".yaml" and ".yml" filename endings for yaml --- rswag-api/lib/rswag/api/middleware.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rswag-api/lib/rswag/api/middleware.rb b/rswag-api/lib/rswag/api/middleware.rb index c1a4fbb..7256794 100644 --- a/rswag-api/lib/rswag/api/middleware.rb +++ b/rswag-api/lib/rswag/api/middleware.rb @@ -31,7 +31,7 @@ module Rswag private def parse_file(filename) - if /\.yml$/ === filename + if /\.ya?ml$/ === filename load_yaml(filename) else load_json(filename) From 49b5059273e50342803031e1b2e2774dcc61f74c Mon Sep 17 00:00:00 2001 From: stefanosx Date: Wed, 6 Mar 2019 12:59:24 +0100 Subject: [PATCH 13/83] Update README.md You need to run the generation of rswag:api:install rswag:ui:install in separated lines to work --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 08f0157..5d9b369 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,8 @@ Once you have an API that can describe itself in Swagger, you've opened the trea 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 g rswag:api:install + rails g rswag:ui:install RAILS_ENV=test rails g rswag:specs:install ``` From f969fb6573f67a6e1e53cf66b8a776f9bec4cb6e Mon Sep 17 00:00:00 2001 From: Olle Jonsson Date: Wed, 17 Apr 2019 14:46:26 +0200 Subject: [PATCH 14/83] CONTRIBUTING: Correct URL --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 618eda5..46eb827 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,8 +3,8 @@ Fork, then clone the repo: ``` -git clone git@github.com:your-username/swagger_rails.git -cd swagger_rails +git clone git@github.com:domaindrivendev/rswag.git +cd rswag ``` Set up your machine: @@ -28,6 +28,6 @@ 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]. +Push to your fork and [submit a Pull Request][pr]. -[pr]: https://github.com/domaindrivendev/swagger_rails/compare/ +[pr]: https://github.com/domaindrivendev/rswag/compare/ From a00145c1f77776ac18e2303d049aa093a95f22e1 Mon Sep 17 00:00:00 2001 From: Igor Zubkov Date: Tue, 20 Aug 2019 16:51:27 +0300 Subject: [PATCH 15/83] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ac0e3e..9e2259f 100644 --- a/README.md +++ b/README.md @@ -486,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 ### From ac65dc17803b915e0770f7b0ca2b11afb573cdd3 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 22:35:54 -0300 Subject: [PATCH 16/83] Gemfile / gemspec files compatible with Rails 6 --- .ruby-version | 2 +- Gemfile | 2 +- rswag-api/rswag-api.gemspec | 2 +- rswag-specs/rswag-specs.gemspec | 4 ++-- rswag-ui/rswag-ui.gemspec | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.ruby-version b/.ruby-version index 2bf1c1c..ec1cf33 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.3.1 +2.6.3 diff --git a/Gemfile b/Gemfile index bbd3d73..d351ace 100644 --- a/Gemfile +++ b/Gemfile @@ -9,7 +9,7 @@ gem 'rails', "#{rails_version}" case rails_version.split('.').first when '3' gem 'strong_parameters' -when '4', '5' +when '4', '5', '6' gem 'responders' end 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/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-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 From 621d6f47540df542a451d330386dde452365f4a4 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 22:37:22 -0300 Subject: [PATCH 17/83] Updating travis file and adding Rails 6 to build matrix --- .travis.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index bdf321a..ce0f6fd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,16 +1,17 @@ language: ruby rvm: - - 2.2.5 + - 2.6.3 env: + - RAILS_VERSION=6.0.0 - RAILS_VERSION=5.2.0 - RAILS_VERSION=4.2.0 - RAILS_VERSION=3.2.22 cache: directories: - - /home/travis/.rvm/gems/ruby-2.2.5 + - /home/travis/.rvm/gems/ruby-2.6.3 install: ./ci/build.sh From 16458d458ac3adfdb8b8b021afeac9fddd7444c6 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 22:45:12 -0300 Subject: [PATCH 18/83] Adding extra lib to fix build --- .travis.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.travis.yml b/.travis.yml index ce0f6fd..2327462 100644 --- a/.travis.yml +++ b/.travis.yml @@ -9,6 +9,12 @@ env: - RAILS_VERSION=4.2.0 - RAILS_VERSION=3.2.22 +addons: + apt: + packages: + - libqtwebkit-dev + - libqtwebkit4 + cache: directories: - /home/travis/.rvm/gems/ruby-2.6.3 From 7179802fe07e5650375dfa17d78bd981522fcbf1 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 22:50:28 -0300 Subject: [PATCH 19/83] Using alternative config for xfvb --- .travis.yml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.travis.yml b/.travis.yml index 2327462..2e9171b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,9 @@ language: ruby +dist: xenial +services: + - xvfb + rvm: - 2.6.3 @@ -21,11 +25,6 @@ cache: install: ./ci/build.sh -before_script: - - export DISPLAY=:99.0 - - sh -e /etc/init.d/xvfb start - - sleep 3 - script: ./ci/test.sh jobs: From d37933801716d6e6ff3a30053d95512f81b65d4f Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 23:00:07 -0300 Subject: [PATCH 20/83] Enforce SQlite version --- Gemfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index d351ace..a688e2c 100644 --- a/Gemfile +++ b/Gemfile @@ -13,7 +13,7 @@ when '4', '5', '6' gem 'responders' end -gem 'sqlite3' +gem 'sqlite3', '1.4.1' gem 'rswag-api', path: './rswag-api' gem 'rswag-ui', path: './rswag-ui' From 586d0211ff06f33023c49ad4bfc427afa6a25095 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 23:06:19 -0300 Subject: [PATCH 21/83] Force SQlite 1.3 version --- Gemfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index a688e2c..c9ebb7b 100644 --- a/Gemfile +++ b/Gemfile @@ -13,7 +13,7 @@ when '4', '5', '6' gem 'responders' end -gem 'sqlite3', '1.4.1' +gem 'sqlite3', '~> 1.3.6' gem 'rswag-api', path: './rswag-api' gem 'rswag-ui', path: './rswag-ui' From 91a0f88eb5d96753cbda8593ed75dcb2b1c4671f Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 23:11:57 -0300 Subject: [PATCH 22/83] Use different Sqlite versions for Rails versions --- Gemfile | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index c9ebb7b..c9d5c4e 100644 --- a/Gemfile +++ b/Gemfile @@ -13,7 +13,12 @@ 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' From 81f8e0dbaff7aef176991808e31f56054d00856a Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Sun, 25 Aug 2019 23:19:03 -0300 Subject: [PATCH 23/83] Removing Rails 3/4 - they are not supported by the Rails Core Team --- .travis.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index 2e9171b..f9edbb2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,8 +10,6 @@ rvm: env: - RAILS_VERSION=6.0.0 - RAILS_VERSION=5.2.0 - - RAILS_VERSION=4.2.0 - - RAILS_VERSION=3.2.22 addons: apt: From 6c684729d11336fb77365d0a04214f3151c2d089 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Mon, 23 Sep 2019 22:56:24 -0300 Subject: [PATCH 24/83] Use updated ruby version --- .ruby-version | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ruby-version b/.ruby-version index ec1cf33..2714f53 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.6.3 +2.6.4 From 4bdbd7ed9843e6e1fb10e0e414f53f67e9d71608 Mon Sep 17 00:00:00 2001 From: Thiago Pradi Date: Mon, 23 Sep 2019 23:03:09 -0300 Subject: [PATCH 25/83] Use updated ruby on CI too --- .travis.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index f9edbb2..304c64c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,7 +5,7 @@ services: - xvfb rvm: - - 2.6.3 + - 2.6.4 env: - RAILS_VERSION=6.0.0 @@ -19,7 +19,7 @@ addons: cache: directories: - - /home/travis/.rvm/gems/ruby-2.6.3 + - /home/travis/.rvm/gems/ruby-2.6.4 install: ./ci/build.sh From b7a6b2de8bbe6f07ec5b3025f277c5d55ffae47f Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Mon, 30 Sep 2019 21:06:14 +0100 Subject: [PATCH 26/83] Update README.md Repoint readme links --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0ac0e3e..e783234 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.17.3| +|[2.0.5](https://github.com/rswag/rswag/tree/2.0.4)|2.0|3.17.3| +|[1.6.0](https://github.com/rswag/rswag/tree/1.6.0)|2.0|2.2.5| ## Getting Started ## From 8bdf3eac083915ecae1e94bdab8afcc756441b39 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Wed, 2 Oct 2019 13:50:56 +0100 Subject: [PATCH 27/83] Update the contributing doc, referencing the CI files --- CONTRIBUTING.md | 26 +++++++++++++++++++------- test-app/db/schema.rb | 12 ++++++------ 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46eb827..f406098 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,24 +1,36 @@ # Contributing -Fork, then clone the repo: - +## Fork, then clone the repo: ``` -git clone git@github.com:domaindrivendev/rswag.git +git clone git@github.com:rswag/rswag.git cd rswag ``` +## Build Set up your machine: - +``` +./ci/build.sh +``` +Or manually ``` bundle -cd spec/dummy +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 ``` @@ -30,4 +42,4 @@ bundle exec rspec Push to your fork and [submit a Pull Request][pr]. -[pr]: https://github.com/domaindrivendev/rswag/compare/ +[pr]: https://github.com/rswag/rswag/compare/ diff --git a/test-app/db/schema.rb b/test-app/db/schema.rb index 8accba1..e01f8f3 100644 --- a/test-app/db/schema.rb +++ b/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 -# database schema. If you need to create the application database on another -# system, you should be using db:schema:load, not running all the migrations -# from scratch. The latter is a flawed and unsustainable approach (the more migrations -# you'll amass, the slower it'll run and the greater likelihood for issues). +# This file is the source Rails uses to define your schema when running `rails +# db:schema:load`. When creating a new database, `rails db:schema:load` tends to +# be faster and is potentially less error prone than running all of your +# migrations from scratch. Old migrations may fail to apply correctly if those +# 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" From 3329c1ec55555c7adbc66ce17aca457cc88afe02 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Wed, 2 Oct 2019 14:10:12 +0100 Subject: [PATCH 28/83] Add Changelog Fix #38 --- CHANGELOG.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8d7499e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +# 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 +- 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 \ No newline at end of file From a3aa56e2df23a7367f7ae1568f8ee874bbb66162 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Thu, 3 Oct 2019 22:37:48 +0100 Subject: [PATCH 29/83] Add a message on how to release to contributing guide --- CHANGELOG.md | 10 +++++++++- CONTRIBUTING.md | 14 ++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d7499e..0a8b599 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [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 @@ -15,4 +23,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed ### Security -## [2.0.5] - 2018-07-10 \ No newline at end of file +## [2.0.5] - 2018-07-10 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f406098..c22b355 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,3 +43,17 @@ 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. From 0246ff164fcd418969d6309af257ed1bbb007b6e Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Thu, 3 Oct 2019 23:00:27 +0100 Subject: [PATCH 30/83] Update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 045cda0..267b563 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ 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)|2.0|3.17.3| -|[2.0.5](https://github.com/rswag/rswag/tree/2.0.4)|2.0|3.17.3| +|[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 ## From 5c9154864e90115c299eea87308d0332da97514a Mon Sep 17 00:00:00 2001 From: Peter McCready Date: Fri, 4 Oct 2019 14:51:41 +0100 Subject: [PATCH 31/83] add options and trace verbs --- rswag-specs/lib/rswag/specs/example_group_helpers.rb | 2 +- .../spec/rswag/specs/example_group_helpers_spec.rb | 2 +- test-app/db/schema.rb | 12 ++++++------ 3 files changed, 8 insertions(+), 8 deletions(-) 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/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/test-app/db/schema.rb b/test-app/db/schema.rb index e01f8f3..8accba1 100644 --- a/test-app/db/schema.rb +++ b/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. # -# This file is the source Rails uses to define your schema when running `rails -# db:schema:load`. When creating a new database, `rails db:schema:load` tends to -# be faster and is potentially less error prone than running all of your -# migrations from scratch. Old migrations may fail to apply correctly if those -# migrations use external dependencies or application code. +# Note that this schema.rb definition is the authoritative source for your +# database schema. If you need to create the application database on another +# system, you should be using db:schema:load, not running all the migrations +# from scratch. The latter is a flawed and unsustainable approach (the more migrations +# you'll amass, the slower it'll run and the greater likelihood for issues). # # It's strongly recommended that you check this file into your version control system. -ActiveRecord::Schema.define(version: 2016_02_18_212104) do +ActiveRecord::Schema.define(version: 20160218212104) do create_table "blogs", force: :cascade do |t| t.string "title" From 57da84d05504c00b21b94a38cb59b9fc63345f9c Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Fri, 4 Oct 2019 14:52:47 +0100 Subject: [PATCH 32/83] add options and trace --- rswag-specs/lib/rswag/specs/example_group_helpers.rb | 2 +- rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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/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 From bff44ee06e7ddd94fb6ab1510af7fbeb0d1f3b24 Mon Sep 17 00:00:00 2001 From: Hayley Date: Mon, 7 Oct 2019 16:55:20 +0100 Subject: [PATCH 33/83] update swagger-ui to 3.23.11 --- README.md | 2 +- package-lock.json | 3 +++ rswag-ui/package.json | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 package-lock.json diff --git a/README.md b/README.md index 267b563..d3cfe2f 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ 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)|2.0|3.17.3| +|[master](https://github.com/rswag/rswag/tree/master)|2.0|3.23.11| |[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| diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..48e341a --- /dev/null +++ b/package-lock.json @@ -0,0 +1,3 @@ +{ + "lockfileVersion": 1 +} diff --git a/rswag-ui/package.json b/rswag-ui/package.json index 1fce627..fd299d1 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.23.11" } } From 90df5bfa30cf5a18d3740e078a594b9a2b799490 Mon Sep 17 00:00:00 2001 From: Hayley Date: Mon, 7 Oct 2019 17:11:16 +0100 Subject: [PATCH 34/83] update package-lock --- package-lock.json | 3 --- rswag-ui/package-lock.json | 6 +++--- 2 files changed, 3 insertions(+), 6 deletions(-) delete mode 100644 package-lock.json diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 48e341a..0000000 --- a/package-lock.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "lockfileVersion": 1 -} diff --git a/rswag-ui/package-lock.json b/rswag-ui/package-lock.json index 664d3fa..8bc72e8 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.23.11", + "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.23.11.tgz", + "integrity": "sha512-ipENHHH/sqpngTpHXUwg55eAOZ7b2UVayUwwuWPA6nQSPhjBVXX4zOPpNKUwQIFOl3oIwVvZF7mqoxH7pMgVzA==" } } } From 2c3c23e46089d97506c6b7f3b9007abe8dc6f57c Mon Sep 17 00:00:00 2001 From: Hayley Date: Mon, 7 Oct 2019 17:23:25 +0100 Subject: [PATCH 35/83] update changelog.md and contributing.md --- CHANGELOG.md | 1 + CONTRIBUTING.md | 13 +++++++++++++ 2 files changed, 14 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a8b599..450d1a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added ### Changed +- Update swagger-ui version to 3.23.11 [#239](https://github.com/rswag/rswag/pull/239) ### Deprecated ### Removed ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c22b355..a1b9b5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,6 +44,19 @@ Push to your fork and [submit a Pull Request][pr]. [pr]: https://github.com/rswag/rswag/compare/ +## Updating Swagger UI + +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 +``` + +Navigate to the rswag-ui folder and run npm install to update the package-lock.json + + ## Release (for maintainers) From ac1d61b08f886824659757e1c39e4730b9bf6180 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Tue, 8 Oct 2019 15:57:16 +0100 Subject: [PATCH 36/83] Replace webdriver with firefox-headless --- Gemfile | 3 ++- test-app/db/schema.rb | 12 ++++++------ test-app/spec/rails_helper.rb | 11 +++++++---- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/Gemfile b/Gemfile index c9d5c4e..b9f1fbe 100644 --- a/Gemfile +++ b/Gemfile @@ -28,7 +28,8 @@ group :test do gem 'rspec-rails' gem 'generator_spec' gem 'capybara' - gem 'capybara-webkit' + gem 'geckodriver-helper' + gem 'selenium-webdriver' gem 'rswag-specs', path: './rswag-specs' end diff --git a/test-app/db/schema.rb b/test-app/db/schema.rb index 8accba1..e01f8f3 100644 --- a/test-app/db/schema.rb +++ b/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 -# database schema. If you need to create the application database on another -# system, you should be using db:schema:load, not running all the migrations -# from scratch. The latter is a flawed and unsustainable approach (the more migrations -# you'll amass, the slower it'll run and the greater likelihood for issues). +# This file is the source Rails uses to define your schema when running `rails +# db:schema:load`. When creating a new database, `rails db:schema:load` tends to +# be faster and is potentially less error prone than running all of your +# migrations from scratch. Old migrations may fail to apply correctly if those +# 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" diff --git a/test-app/spec/rails_helper.rb b/test-app/spec/rails_helper.rb index 98c8fc3..3d9bd5f 100644 --- a/test-app/spec/rails_helper.rb +++ b/test-app/spec/rails_helper.rb @@ -51,9 +51,12 @@ RSpec.configure do |config| # arbitrary gems may also be filtered via: # config.filter_gems_from_backtrace("gem name") - Capybara.javascript_driver = :webkit -end + Capybara.register_driver :firefox_headless do |app| + options = ::Selenium::WebDriver::Firefox::Options.new + options.args << '--headless' -Capybara::Webkit.configure do |config| - config.block_unknown_urls + Capybara::Selenium::Driver.new(app, browser: :firefox, options: options) + end + + Capybara.javascript_driver = :firefox_headless end From dc2ebd94bb701883581bd1b92db6d77766bb4285 Mon Sep 17 00:00:00 2001 From: Hayley Date: Tue, 8 Oct 2019 16:18:55 +0100 Subject: [PATCH 37/83] update swagger ui to 3.18.2 --- CHANGELOG.md | 1 + README.md | 2 +- rswag-ui/package-lock.json | 6 +++--- rswag-ui/package.json | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a8b599..7f30a85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added ### Changed +- Update swagger-ui to 3.18.2 ### Deprecated ### Removed ### Fixed diff --git a/README.md b/README.md index 267b563..3cfff07 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ 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)|2.0|3.17.3| +|[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| 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" } } From d01dff199cfa356d5d082409d102c8ba0f863c45 Mon Sep 17 00:00:00 2001 From: Hayley Date: Tue, 8 Oct 2019 16:43:11 +0100 Subject: [PATCH 38/83] potential test fix --- test-app/spec/features/swagger_ui_spec.rb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test-app/spec/features/swagger_ui_spec.rb b/test-app/spec/features/swagger_ui_spec.rb index 7faa14e..5b90f88 100644 --- a/test-app/spec/features/swagger_ui_spec.rb +++ b/test-app/spec/features/swagger_ui_spec.rb @@ -5,8 +5,8 @@ feature 'swagger-ui', js: true do scenario 'browsing api-docs' do visit '/api-docs' - expect(page).to have_content('GET /blogs Searches blogs') - expect(page).to have_content('POST /blogs Creates a blog') - expect(page).to have_content('GET /blogs/{id} Retrieves a blog') + expect(page).to have_content('GET /blogs Searches blogs', normalize_ws: true) + expect(page).to have_content('POST /blogs Creates a blog', normalize_ws: true) + expect(page).to have_content('GET /blogs/{id} Retrieves a blog', normalize_ws: true) end end From 3542cd0857ea42a63aabdc49ebfc8935e5ac1443 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Mon, 14 Oct 2019 22:17:12 +0100 Subject: [PATCH 39/83] Add a Sprockets 4 manifest Fix #243 --- test-app/app/assets/config/manifest.js | 2 ++ test-app/app/assets/images/.keep | 0 2 files changed, 2 insertions(+) create mode 100644 test-app/app/assets/config/manifest.js create mode 100644 test-app/app/assets/images/.keep diff --git a/test-app/app/assets/config/manifest.js b/test-app/app/assets/config/manifest.js new file mode 100644 index 0000000..5918193 --- /dev/null +++ b/test-app/app/assets/config/manifest.js @@ -0,0 +1,2 @@ +//= link_tree ../images +//= link_directory ../stylesheets .css diff --git a/test-app/app/assets/images/.keep b/test-app/app/assets/images/.keep new file mode 100644 index 0000000..e69de29 From 77d00407a4e0a6de2f4a37b5a4b49458d4e37915 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Wed, 16 Oct 2019 20:51:53 +0100 Subject: [PATCH 40/83] whitespace linting --- rswag-specs/lib/rswag/specs/extended_schema.rb | 4 ++-- rswag-specs/lib/rswag/specs/railtie.rb | 2 +- rswag-specs/lib/rswag/specs/request_factory.rb | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/rswag-specs/lib/rswag/specs/extended_schema.rb b/rswag-specs/lib/rswag/specs/extended_schema.rb index 62eb4ee..29888f8 100644 --- a/rswag-specs/lib/rswag/specs/extended_schema.rb +++ b/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 diff --git a/rswag-specs/lib/rswag/specs/railtie.rb b/rswag-specs/lib/rswag/specs/railtie.rb index 43e2302..994a8a4 100644 --- a/rswag-specs/lib/rswag/specs/railtie.rb +++ b/rswag-specs/lib/rswag/specs/railtie.rb @@ -5,7 +5,7 @@ module Rswag rake_tasks do load File.expand_path('../../../tasks/rswag-specs_tasks.rake', __FILE__) end - + generators do require 'generators/rspec/swagger/swagger_generator.rb' end diff --git a/rswag-specs/lib/rswag/specs/request_factory.rb b/rswag-specs/lib/rswag/specs/request_factory.rb index 7106015..14b1edc 100644 --- a/rswag-specs/lib/rswag/specs/request_factory.rb +++ b/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 ] From 778d25038558cb59cf6d2c20fac6bd6877b011d8 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Wed, 16 Oct 2019 21:12:36 +0100 Subject: [PATCH 41/83] Split file join path --- rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb b/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb index 48f92aa..81feeb9 100644 --- a/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb +++ b/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb @@ -11,7 +11,7 @@ module Rspec end def create_spec_file - template 'spec.rb', File.join('spec/requests', "#{controller_path}_spec.rb") + template 'spec.rb', File.join('spec', 'requests', "#{controller_path}_spec.rb") end private From 189a7ef06136e42307c2d8b9d1c9a438d48add3e Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Wed, 16 Oct 2019 22:05:14 +0100 Subject: [PATCH 42/83] Move spec generator files, organize whitespace in generator output --- .../lib/generators/rspec/{swagger => }/USAGE | 0 .../rspec/swagger/swagger_generator.rb | 24 ------- .../lib/generators/rspec/swagger_generator.rb | 22 +++++++ .../rspec/{swagger => }/templates/spec.rb | 24 +++---- .../lib/rspec/rails/swagger/route_parser.rb | 62 ------------------- rswag-specs/lib/rswag/route_parser.rb | 58 +++++++++++++++++ 6 files changed, 92 insertions(+), 98 deletions(-) rename rswag-specs/lib/generators/rspec/{swagger => }/USAGE (100%) delete mode 100644 rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb create mode 100644 rswag-specs/lib/generators/rspec/swagger_generator.rb rename rswag-specs/lib/generators/rspec/{swagger => }/templates/spec.rb (59%) delete mode 100644 rswag-specs/lib/rspec/rails/swagger/route_parser.rb create mode 100644 rswag-specs/lib/rswag/route_parser.rb diff --git a/rswag-specs/lib/generators/rspec/swagger/USAGE b/rswag-specs/lib/generators/rspec/USAGE similarity index 100% rename from rswag-specs/lib/generators/rspec/swagger/USAGE rename to rswag-specs/lib/generators/rspec/USAGE diff --git a/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb b/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb deleted file mode 100644 index 81feeb9..0000000 --- a/rswag-specs/lib/generators/rspec/swagger/swagger_generator.rb +++ /dev/null @@ -1,24 +0,0 @@ -require 'rspec/rails/swagger/route_parser' -require 'rails/generators' - -module Rspec - module Generators - class SwaggerGenerator < ::Rails::Generators::NamedBase - source_root File.expand_path('../templates', __FILE__) - - def setup - @routes = RSpec::Rails::Swagger::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 -end diff --git a/rswag-specs/lib/generators/rspec/swagger_generator.rb b/rswag-specs/lib/generators/rspec/swagger_generator.rb new file mode 100644 index 0000000..ddb862c --- /dev/null +++ b/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 diff --git a/rswag-specs/lib/generators/rspec/swagger/templates/spec.rb b/rswag-specs/lib/generators/rspec/templates/spec.rb similarity index 59% rename from rswag-specs/lib/generators/rspec/swagger/templates/spec.rb rename to rswag-specs/lib/generators/rspec/templates/spec.rb index 75ff7b3..0673596 100644 --- a/rswag-specs/lib/generators/rspec/swagger/templates/spec.rb +++ b/rswag-specs/lib/generators/rspec/templates/spec.rb @@ -1,22 +1,22 @@ require 'swagger_helper' RSpec.describe '<%= controller_path %>', type: :request do - <% @routes.each do | template, path_item | %> +<% @routes.each do | template, path_item | %> path '<%= template %>' do -<% unless path_item[:params].empty? -%> +<% unless path_item[:params].empty? -%> # You'll want to customize the parameter types... - <% path_item[:params].each do |param| -%> +<% path_item[:params].each do |param| -%> parameter '<%= param %>', in: :body, type: :string - <% end -%> -<% end -%> -<% path_item[:actions].each do | action, details | -%> +<% 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| -%> +<% unless path_item[:params].empty? -%> +<% path_item[:params].each do |param| -%> let(:<%= param %>) { '123' } - <% end -%> -<% end -%> +<% end -%> +<% end -%> after do |example| example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) } @@ -24,7 +24,7 @@ RSpec.describe '<%= controller_path %>', type: :request do run_test! end end -<% end -%> +<% end -%> end -<% end -%> +<% end -%> end diff --git a/rswag-specs/lib/rspec/rails/swagger/route_parser.rb b/rswag-specs/lib/rspec/rails/swagger/route_parser.rb deleted file mode 100644 index 9ab9513..0000000 --- a/rswag-specs/lib/rspec/rails/swagger/route_parser.rb +++ /dev/null @@ -1,62 +0,0 @@ -module RSpec - module Rails - module Swagger - 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 - end -end diff --git a/rswag-specs/lib/rswag/route_parser.rb b/rswag-specs/lib/rswag/route_parser.rb new file mode 100644 index 0000000..523b36b --- /dev/null +++ b/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 From 4d29e090109e3de9732391b400097afb4afac7eb Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Wed, 16 Oct 2019 23:19:24 +0100 Subject: [PATCH 43/83] Add spec generator test --- .../lib/generators/rspec/templates/spec.rb | 2 +- .../generators/rspec/fixtures/spec/.gitkeep | 0 .../rspec/swagger_generator_spec.rb | 44 +++++++++++++++++++ 3 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 rswag-specs/spec/generators/rspec/fixtures/spec/.gitkeep create mode 100644 rswag-specs/spec/generators/rspec/swagger_generator_spec.rb diff --git a/rswag-specs/lib/generators/rspec/templates/spec.rb b/rswag-specs/lib/generators/rspec/templates/spec.rb index 0673596..346e348 100644 --- a/rswag-specs/lib/generators/rspec/templates/spec.rb +++ b/rswag-specs/lib/generators/rspec/templates/spec.rb @@ -6,7 +6,7 @@ RSpec.describe '<%= controller_path %>', type: :request do <% unless path_item[:params].empty? -%> # You'll want to customize the parameter types... <% path_item[:params].each do |param| -%> - parameter '<%= param %>', in: :body, type: :string + parameter name: '<%= param %>', in: :path, type: :string, description: '<%= param %>' <% end -%> <% end -%> <% path_item[:actions].each do | action, details | %> diff --git a/rswag-specs/spec/generators/rspec/fixtures/spec/.gitkeep b/rswag-specs/spec/generators/rspec/fixtures/spec/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/rswag-specs/spec/generators/rspec/swagger_generator_spec.rb b/rswag-specs/spec/generators/rspec/swagger_generator_spec.rb new file mode 100644 index 0000000..f11ea65 --- /dev/null +++ b/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 From 07c4c74d75c2e8cead3b891e36b1e516e4196725 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Thu, 17 Oct 2019 00:02:09 +0100 Subject: [PATCH 44/83] Update changelog --- CHANGELOG.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f30a85..fa57b8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,21 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added ### Changed -- Update swagger-ui to 3.18.2 ### Deprecated ### Removed ### Fixed ### Security +## [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) -### Deprecated -### Removed -### Fixed -### Security ## [2.0.5] - 2018-07-10 From 28245d4dd0248b0566315e4f654d38a11633fc80 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Thu, 17 Oct 2019 10:02:24 +0100 Subject: [PATCH 45/83] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 02d3dff..07cc88d 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ 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)|2.0|3.18.2| -|[2.0.6](https://github.com/rswag/rswag/tree/2.0.6)|2.0|3.17.3| +|[2.1.0](https://github.com/rswag/rswag/tree/2.1.0)|2.0|3.18.2| |[1.6.0](https://github.com/rswag/rswag/tree/1.6.0)|2.0|2.2.5| ## Getting Started ## From e5eb44191c21f8af81b007421cfd9107d3faf6de Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Fri, 21 Sep 2018 17:31:28 +0700 Subject: [PATCH 46/83] Use RSpec.describe to fix IRB context warning in Rails console --- .../spec/generators/rswag/specs/install_generator_spec.rb | 2 +- rswag-specs/spec/rswag/specs/configuration_spec.rb | 2 +- rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb | 2 +- rswag-specs/spec/rswag/specs/example_helpers_spec.rb | 4 ++-- rswag-specs/spec/rswag/specs/request_factory_spec.rb | 4 ++-- rswag-specs/spec/rswag/specs/response_validator_spec.rb | 4 ++-- rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb | 6 +++--- test-app/spec/features/swagger_ui_spec.rb | 2 +- test-app/spec/integration/auth_tests_spec.rb | 2 +- test-app/spec/integration/blogs_spec.rb | 2 +- test-app/spec/rake/rswag_specs_swaggerize_spec.rb | 4 ++-- 11 files changed, 17 insertions(+), 17 deletions(-) diff --git a/rswag-specs/spec/generators/rswag/specs/install_generator_spec.rb b/rswag-specs/spec/generators/rswag/specs/install_generator_spec.rb index 39dc6fe..809e4f6 100644 --- a/rswag-specs/spec/generators/rswag/specs/install_generator_spec.rb +++ b/rswag-specs/spec/generators/rswag/specs/install_generator_spec.rb @@ -4,7 +4,7 @@ require 'generators/rswag/specs/install/install_generator' module Rswag module Specs - describe InstallGenerator do + RSpec.describe InstallGenerator do include GeneratorSpec::TestCase destination File.expand_path('../tmp', __FILE__) diff --git a/rswag-specs/spec/rswag/specs/configuration_spec.rb b/rswag-specs/spec/rswag/specs/configuration_spec.rb index b75d843..30da333 100644 --- a/rswag-specs/spec/rswag/specs/configuration_spec.rb +++ b/rswag-specs/spec/rswag/specs/configuration_spec.rb @@ -3,7 +3,7 @@ require 'rswag/specs/configuration' module Rswag module Specs - describe Configuration do + RSpec.describe Configuration do subject { described_class.new(rspec_config) } let(:rspec_config) { OpenStruct.new(swagger_root: swagger_root, swagger_docs: swagger_docs) } 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 c870bfc..ed667ca 100644 --- a/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb +++ b/rswag-specs/spec/rswag/specs/example_group_helpers_spec.rb @@ -3,7 +3,7 @@ require 'rswag/specs/example_group_helpers' module Rswag module Specs - describe ExampleGroupHelpers do + RSpec.describe ExampleGroupHelpers do subject { double('example_group') } before do diff --git a/rswag-specs/spec/rswag/specs/example_helpers_spec.rb b/rswag-specs/spec/rswag/specs/example_helpers_spec.rb index 3b22af4..283d4fd 100644 --- a/rswag-specs/spec/rswag/specs/example_helpers_spec.rb +++ b/rswag-specs/spec/rswag/specs/example_helpers_spec.rb @@ -3,7 +3,7 @@ require 'rswag/specs/example_helpers' module Rswag module Specs - describe ExampleHelpers do + RSpec.describe ExampleHelpers do subject { double('example') } before do @@ -12,7 +12,7 @@ module Rswag allow(config).to receive(:get_swagger_doc).and_return(swagger_doc) stub_const('Rswag::Specs::RAILS_VERSION', 3) end - let(:config) { double('config') } + let(:config) { double('config') } let(:swagger_doc) do { securityDefinitions: { diff --git a/rswag-specs/spec/rswag/specs/request_factory_spec.rb b/rswag-specs/spec/rswag/specs/request_factory_spec.rb index f883952..0a70f19 100644 --- a/rswag-specs/spec/rswag/specs/request_factory_spec.rb +++ b/rswag-specs/spec/rswag/specs/request_factory_spec.rb @@ -3,13 +3,13 @@ require 'rswag/specs/request_factory' module Rswag module Specs - describe RequestFactory do + RSpec.describe RequestFactory do subject { RequestFactory.new(config) } before do allow(config).to receive(:get_swagger_doc).and_return(swagger_doc) end - let(:config) { double('config') } + let(:config) { double('config') } let(:swagger_doc) { {} } let(:example) { double('example') } let(:metadata) do diff --git a/rswag-specs/spec/rswag/specs/response_validator_spec.rb b/rswag-specs/spec/rswag/specs/response_validator_spec.rb index 1d05427..9f52b5b 100644 --- a/rswag-specs/spec/rswag/specs/response_validator_spec.rb +++ b/rswag-specs/spec/rswag/specs/response_validator_spec.rb @@ -3,13 +3,13 @@ require 'rswag/specs/response_validator' module Rswag module Specs - describe ResponseValidator do + RSpec.describe ResponseValidator do subject { ResponseValidator.new(config) } before do allow(config).to receive(:get_swagger_doc).and_return(swagger_doc) end - let(:config) { double('config') } + let(:config) { double('config') } let(:swagger_doc) { {} } let(:example) { double('example') } let(:metadata) do diff --git a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb index f904fa5..b5b7ad8 100644 --- a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb +++ b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb @@ -3,8 +3,8 @@ require 'ostruct' module Rswag module Specs - - describe SwaggerFormatter do + + RSpec.describe SwaggerFormatter do subject { described_class.new(output, config) } # Mock out some infrastructure @@ -47,7 +47,7 @@ module Rswag end describe '#stop' do - before do + before do FileUtils.rm_r(swagger_root) if File.exists?(swagger_root) allow(config).to receive(:swagger_docs).and_return( 'v1/swagger.json' => { info: { version: 'v1' } }, diff --git a/test-app/spec/features/swagger_ui_spec.rb b/test-app/spec/features/swagger_ui_spec.rb index 7faa14e..24d5790 100644 --- a/test-app/spec/features/swagger_ui_spec.rb +++ b/test-app/spec/features/swagger_ui_spec.rb @@ -1,6 +1,6 @@ require 'rails_helper' -feature 'swagger-ui', js: true do +RSpec.feature 'swagger-ui', js: true do scenario 'browsing api-docs' do visit '/api-docs' diff --git a/test-app/spec/integration/auth_tests_spec.rb b/test-app/spec/integration/auth_tests_spec.rb index 8e47d2e..573219e 100644 --- a/test-app/spec/integration/auth_tests_spec.rb +++ b/test-app/spec/integration/auth_tests_spec.rb @@ -1,6 +1,6 @@ require 'swagger_helper' -describe 'Auth Tests API', type: :request, swagger_doc: 'v1/swagger.json' do +RSpec.describe 'Auth Tests API', type: :request, swagger_doc: 'v1/swagger.json' do path '/auth-tests/basic' do post 'Authenticates with basic auth' do diff --git a/test-app/spec/integration/blogs_spec.rb b/test-app/spec/integration/blogs_spec.rb index abca570..28ee892 100644 --- a/test-app/spec/integration/blogs_spec.rb +++ b/test-app/spec/integration/blogs_spec.rb @@ -1,6 +1,6 @@ require 'swagger_helper' -describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do +RSpec.describe 'Blogs API', type: :request, swagger_doc: 'v1/swagger.json' do let(:api_key) { 'fake_key' } path '/blogs' do diff --git a/test-app/spec/rake/rswag_specs_swaggerize_spec.rb b/test-app/spec/rake/rswag_specs_swaggerize_spec.rb index 0a590ee..27fc195 100644 --- a/test-app/spec/rake/rswag_specs_swaggerize_spec.rb +++ b/test-app/spec/rake/rswag_specs_swaggerize_spec.rb @@ -1,9 +1,9 @@ require 'spec_helper' require 'rake' -describe 'rswag:specs:swaggerize' do +RSpec.describe 'rswag:specs:swaggerize' do let(:swagger_root) { Rails.root.to_s + '/swagger' } - before do + before do TestApp::Application.load_tasks FileUtils.rm_r(swagger_root) if File.exists?(swagger_root) end From 1d5ed8345f12a101795c2ad4aa05689531f89d5e Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Thu, 17 Oct 2019 13:37:36 +0100 Subject: [PATCH 47/83] add a PR template --- .github/pull_request_template.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..3eda872 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,12 @@ +## Problem + +## Solution + +### Related Issues + +### Checklist +- [ ] Added tests +- [ ] Changelog updated + +### Steps to Test or Reproduce +Outline the steps to test or reproduce the PR here. \ No newline at end of file From 29becf98f8a131295352f015ad915fe131b6f5bc Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Thu, 17 Oct 2019 14:16:46 +0100 Subject: [PATCH 48/83] add issue templates --- .github/ISSUE_TEMPLATE/bug_report.md | 14 ++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 11 +++++++++++ .../pull_request_template.md | 0 3 files changed, 25 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md rename .github/{ => PULL_REQUEST_TEMPLATE}/pull_request_template.md (100%) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..7a24179 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,14 @@ +## Describe the bug +A clear and concise description of what the bug is. + +## Steps to Test or Reproduce +Steps to reproduce the behavior: + +## Expected behavior +A clear and concise description of what you expected to happen. + +## Screenshots +If applicable, add screenshots to help explain your problem. + +## Additional context +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bde1cd0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,11 @@ +## Is your feature request related to a problem? Please describe. +A clear and concise description of what the problem is. + +## Describe the solution you'd like +A clear and concise description of what you want to happen. + +## Describe alternatives you've considered +A clear and concise description of any alternative solutions or features you've considered. + +## Additional context +Add any other context or screenshots about the feature request here. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md similarity index 100% rename from .github/pull_request_template.md rename to .github/PULL_REQUEST_TEMPLATE/pull_request_template.md From 5b1dde772a38ff03fbc9861d4d8a3f730b69113a Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Thu, 17 Oct 2019 14:27:07 +0100 Subject: [PATCH 49/83] Update pr template --- .github/PULL_REQUEST_TEMPLATE/pull_request_template.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 3eda872..4fc530f 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -1,8 +1,11 @@ ## Problem +A clear and concise description of what the problem is. ## Solution +A clear and concise description of the solution. ### Related Issues +Links to any related issues. ### Checklist - [ ] Added tests From a18d9e51633fca68d376dbb1280b11b648e373e3 Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Thu, 17 Oct 2019 14:36:25 +0100 Subject: [PATCH 50/83] update copy --- .github/PULL_REQUEST_TEMPLATE/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 4fc530f..73c44a1 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -2,7 +2,7 @@ A clear and concise description of what the problem is. ## Solution -A clear and concise description of the solution. +A clear and concise description of what the solution is. ### Related Issues Links to any related issues. From 8d7385fcac86def49e0e989d9ae9f925bc660aeb Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Thu, 17 Oct 2019 16:22:12 +0100 Subject: [PATCH 51/83] update copy --- .github/ISSUE_TEMPLATE/bug_report.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 7a24179..57df306 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -2,7 +2,7 @@ A clear and concise description of what the bug is. ## Steps to Test or Reproduce -Steps to reproduce the behavior: +Please provide an example repo or the steps to reproduce the behavior. ## Expected behavior A clear and concise description of what you expected to happen. @@ -12,3 +12,6 @@ If applicable, add screenshots to help explain your problem. ## Additional context Add any other context about the problem here. + +## Rswag Version +The version of rswag are you using. From ea2ed6ca49fa28d2094cc53f4ca8f3e9354ad70b Mon Sep 17 00:00:00 2001 From: Laura Watson Date: Thu, 17 Oct 2019 17:18:27 +0100 Subject: [PATCH 52/83] Update README --- README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 07cc88d..12c27b1 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,15 @@ Once you have an API that can describe itself in Swagger, you've opened the trea gem 'rswag' ``` - or if you like to avoid loading rspec in other bundler groups. + or if you like to avoid loading rspec in other bundler groups load the rswag-specs component separately. + Note: Adding it to the :development group is not strictly necessary, but without it, generators and rake tasks must be preceded by RAILS_ENV=test. ```ruby # Gemfile gem 'rswag-api' gem 'rswag-ui' - group :test do + group :development, :test do gem 'rspec-rails' gem 'rswag-specs' end @@ -44,11 +45,11 @@ 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:api:install rails g rswag:ui:install RAILS_ENV=test rails g rswag:specs:install ``` @@ -222,7 +223,7 @@ RSpec.configure do |config| end ``` -#### Supporting multiple versions of API #### +#### 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 @@ -237,14 +238,14 @@ 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. +#### 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 | +| cell1 | cell2 | you should use the folowing syntax, making sure there are no whitespaces at the start of any of the lines: From c14f72a45e47676312c28729bafece2da83ac8e7 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Fri, 18 Oct 2019 23:18:30 +0100 Subject: [PATCH 53/83] Point the railtie to the correct file Fixes #248 --- rswag-specs/lib/rswag/specs/railtie.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rswag-specs/lib/rswag/specs/railtie.rb b/rswag-specs/lib/rswag/specs/railtie.rb index 994a8a4..617403e 100644 --- a/rswag-specs/lib/rswag/specs/railtie.rb +++ b/rswag-specs/lib/rswag/specs/railtie.rb @@ -7,7 +7,7 @@ module Rswag end generators do - require 'generators/rspec/swagger/swagger_generator.rb' + require 'generators/rspec/swagger_generator.rb' end end end From 2cf6812ae0948715b281d8f809d106b0864bc3bb Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 19 Oct 2019 21:39:24 +0100 Subject: [PATCH 54/83] Update README.md --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a39bb68..bbf46e8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ rswag ========= [![Build Status](https://travis-ci.org/rswag/rswag.svg?branch=master)](https://travis-ci.org/rswag/rswag) +[![Maintainability](https://api.codeclimate.com/v1/badges/1175b984edc4610f82ab/maintainability)](https://codeclimate.com/github/rswag/rswag/maintainability) [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. @@ -15,7 +16,7 @@ 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)|2.0|3.18.2| -|[2.1.0](https://github.com/rswag/rswag/tree/2.1.0)|2.0|3.18.2| +|[2.1.1](https://github.com/rswag/rswag/tree/2.1.1)|2.0|3.18.2| |[1.6.0](https://github.com/rswag/rswag/tree/1.6.0)|2.0|2.2.5| ## Getting Started ## From b29373c0c465b59389adb36506275e7de16c8feb Mon Sep 17 00:00:00 2001 From: hdpuk86 Date: Thu, 24 Oct 2019 21:53:48 +0100 Subject: [PATCH 55/83] update swagger-ui to 3.23.11 --- rswag-ui/package-lock.json | 6 ------ rswag-ui/package.json | 4 ---- 2 files changed, 10 deletions(-) diff --git a/rswag-ui/package-lock.json b/rswag-ui/package-lock.json index f1458f1..8bc72e8 100644 --- a/rswag-ui/package-lock.json +++ b/rswag-ui/package-lock.json @@ -5,15 +5,9 @@ "requires": true, "dependencies": { "swagger-ui-dist": { -<<<<<<< HEAD "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.18.2", - "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-3.18.2.tgz", - "integrity": "sha512-pWAEiKkgWUJvjmLW9AojudnutJ+NTn5g6OdNLj1iIJWwCkoy40K3Upwa24DqFbmIE4vLX4XplND61hp2L+s5vg==" ->>>>>>> origin/master } } } diff --git a/rswag-ui/package.json b/rswag-ui/package.json index 9f600c5..fd299d1 100644 --- a/rswag-ui/package.json +++ b/rswag-ui/package.json @@ -3,10 +3,6 @@ "version": "1.0.0", "private": true, "dependencies": { -<<<<<<< HEAD "swagger-ui-dist": "3.23.11" -======= - "swagger-ui-dist": "3.18.2" ->>>>>>> origin/master } } From ef78b0c98f04522a144c80d2ded503fdd2e6d3ce Mon Sep 17 00:00:00 2001 From: Hayley Prior <31411337+hdpuk86@users.noreply.github.com> Date: Thu, 24 Oct 2019 22:06:00 +0100 Subject: [PATCH 56/83] Delete .yarn-integrity --- node_modules/.yarn-integrity | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 node_modules/.yarn-integrity diff --git a/node_modules/.yarn-integrity b/node_modules/.yarn-integrity deleted file mode 100644 index 5e070b6..0000000 --- a/node_modules/.yarn-integrity +++ /dev/null @@ -1,10 +0,0 @@ -{ - "systemParams": "darwin-x64-72", - "modulesFolders": [], - "flags": [], - "linkedModules": [], - "topLevelPatterns": [], - "lockfileEntries": {}, - "files": [], - "artifacts": {} -} \ No newline at end of file From 9cbd85a22a87680353fa75d8c3e7847ccfe456d3 Mon Sep 17 00:00:00 2001 From: Hayley Prior <31411337+hdpuk86@users.noreply.github.com> Date: Thu, 24 Oct 2019 22:06:26 +0100 Subject: [PATCH 57/83] Delete yarn.lock --- yarn.lock | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 yarn.lock diff --git a/yarn.lock b/yarn.lock deleted file mode 100644 index fb57ccd..0000000 --- a/yarn.lock +++ /dev/null @@ -1,4 +0,0 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -# yarn lockfile v1 - - From 73b84101cc7e229dd2d7d401547adb0708306a55 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 10:45:35 +0000 Subject: [PATCH 58/83] Adding yaml as option for generator New installations will get :yaml as it's default with openapi 3 as the version. Old installations will have the key missing and will default to :json with an easy upgrade path. --- .../specs/install/templates/swagger_helper.rb | 10 ++++++-- rswag-specs/lib/rswag/specs.rb | 1 + rswag-specs/lib/rswag/specs/configuration.rb | 8 ++++++ .../spec/rswag/specs/configuration_spec.rb | 25 ++++++++++++++++++- 4 files changed, 41 insertions(+), 3 deletions(-) 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 3855920..327b2c8 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 @@ -13,8 +13,8 @@ RSpec.configure do |config| # document below. You can override this behavior by adding a swagger_doc tag to the # the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json' config.swagger_docs = { - 'v1/swagger.json' => { - swagger: '2.0', + 'v1/swagger.yaml' => { + openapi: '3.0.1', info: { title: 'API V1', version: 'v1' @@ -22,4 +22,10 @@ RSpec.configure do |config| paths: {} } } + + # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'. + # The swagger_docs configuration option has the filename including format in + # the key, this may want to be changed to avoid putting yaml in json files. + # Defaults to json. Accepts ':json' and ':yaml'. + config.swagger_format = :yaml end diff --git a/rswag-specs/lib/rswag/specs.rb b/rswag-specs/lib/rswag/specs.rb index de29ce9..a3f0c16 100644 --- a/rswag-specs/lib/rswag/specs.rb +++ b/rswag-specs/lib/rswag/specs.rb @@ -12,6 +12,7 @@ module Rswag c.add_setting :swagger_root c.add_setting :swagger_docs c.add_setting :swagger_dry_run + c.add_setting :swagger_format c.extend ExampleGroupHelpers, type: :request c.include ExampleHelpers, type: :request end diff --git a/rswag-specs/lib/rswag/specs/configuration.rb b/rswag-specs/lib/rswag/specs/configuration.rb index 4adf33c..4c6ee68 100644 --- a/rswag-specs/lib/rswag/specs/configuration.rb +++ b/rswag-specs/lib/rswag/specs/configuration.rb @@ -31,6 +31,14 @@ module Rswag end end + def swagger_format + @swagger_format ||= begin + @rspec_config.swagger_format = :json if @rspec_config.swagger_format.nil? || @rspec_config.swagger_format.empty? + raise ConfigurationError, "Unknown swagger_format '#{@rspec_config.swagger_format}'" unless [:json, :yaml].include?(@rspec_config.swagger_format) + @rspec_config.swagger_format + end + end + def get_swagger_doc(name) return swagger_docs.values.first if name.nil? raise ConfigurationError, "Unknown swagger_doc '#{name}'" unless swagger_docs[name] diff --git a/rswag-specs/spec/rswag/specs/configuration_spec.rb b/rswag-specs/spec/rswag/specs/configuration_spec.rb index 30da333..e3aacdc 100644 --- a/rswag-specs/spec/rswag/specs/configuration_spec.rb +++ b/rswag-specs/spec/rswag/specs/configuration_spec.rb @@ -6,7 +6,9 @@ module Rswag RSpec.describe Configuration do subject { described_class.new(rspec_config) } - let(:rspec_config) { OpenStruct.new(swagger_root: swagger_root, swagger_docs: swagger_docs) } + let(:rspec_config) do + OpenStruct.new(swagger_root: swagger_root, swagger_docs: swagger_docs, swagger_format: swagger_format) + end let(:swagger_root) { 'foobar' } let(:swagger_docs) do { @@ -14,6 +16,7 @@ module Rswag 'v2/swagger.json' => { info: { title: 'v2' } } } end + let(:swagger_format) { :yaml } describe '#swagger_root' do let(:response) { subject.swagger_root } @@ -46,6 +49,26 @@ module Rswag end end + describe '#swagger_format' do + let(:response) { subject.swagger_format } + + context 'provided in rspec config' do + it { expect(response).to be_an_instance_of(Symbol) } + end + + context 'unsupported format provided' do + let(:swagger_format) { :xml } + + it { expect { response }.to raise_error ConfigurationError } + end + + context 'not provided' do + let(:swagger_format) { nil } + + it { expect(response).to eq(:json) } + end + end + describe '#get_swagger_doc(tag=nil)' do let(:swagger_doc) { subject.get_swagger_doc(tag) } From 0e04635b156011b0d83a246e5038046d5dbb2c67 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 11:19:01 +0000 Subject: [PATCH 59/83] Write the files using specified format --- .../lib/rswag/specs/swagger_formatter.rb | 10 +++++++++- .../rswag/specs/swagger_formatter_spec.rb | 20 ++++++++++++++++--- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb index 794a9d9..b8061dc 100644 --- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb +++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb @@ -37,7 +37,7 @@ module Rswag FileUtils.mkdir_p dirname unless File.exists?(dirname) File.open(file_path, 'w') do |file| - file.write(JSON.pretty_generate(doc)) + file.write(pretty_generate(doc)) end @output.puts "Swagger doc generated at #{file_path}" @@ -46,6 +46,14 @@ module Rswag private + def pretty_generate(doc) + if @config.swagger_format == :yaml + YAML.dump(doc) + else # config errors are thrown in 'def swagger_format', no throw needed here + JSON.pretty_generate(doc) + end + end + def metadata_to_swagger(metadata) response_code = metadata[:response][:code] response = metadata[:response].reject { |k,v| k == :code } diff --git a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb index b5b7ad8..2a29cde 100644 --- a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb +++ b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb @@ -53,14 +53,28 @@ module Rswag 'v1/swagger.json' => { info: { version: 'v1' } }, 'v2/swagger.json' => { info: { version: 'v2' } } ) + allow(config).to receive(:swagger_format).and_return(swagger_format) subject.stop(notification) end let(:notification) { double('notification') } + context 'with default format' do + let(:swagger_format) { :json } - it 'writes the swagger_doc(s) to file' do - expect(File).to exist("#{swagger_root}/v1/swagger.json") - expect(File).to exist("#{swagger_root}/v2/swagger.json") + it 'writes the swagger_doc(s) to file' do + expect(File).to exist("#{swagger_root}/v1/swagger.json") + expect(File).to exist("#{swagger_root}/v2/swagger.json") + expect { JSON.parse(File.read("#{swagger_root}/v2/swagger.json")) }.not_to raise_error + end + end + + context 'with yaml format' do + let(:swagger_format) { :yaml } + + it 'writes the swagger_doc(s) as yaml' do + expect(File).to exist("#{swagger_root}/v1/swagger.json") + expect { JSON.parse(File.read("#{swagger_root}/v1/swagger.json")) }.to raise_error(JSON::ParserError) + end end after do From 3ff1de5d65abc0ee4c52d5b8468b9f65320c7fd9 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 11:40:07 +0000 Subject: [PATCH 60/83] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fa57b8b..bb1a888 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- New swagger_format config option for setting YAML output [#251](https://github.com/rswag/rswag/pull/251) ### Changed ### Deprecated ### Removed From acab437a7d36c3b8c75851c9eae4790f87386da3 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 12:55:09 +0000 Subject: [PATCH 61/83] Add failing test showing Psych errors --- rswag-specs/lib/rswag/specs/swagger_formatter.rb | 2 ++ rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb | 2 ++ 2 files changed, 4 insertions(+) diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb index b8061dc..d16aeb2 100644 --- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb +++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb @@ -48,6 +48,8 @@ module Rswag def pretty_generate(doc) if @config.swagger_format == :yaml + # NOTE: Yaml will quite happily embed ruby-only classes such as symbols. + # clean_doc = stringify(doc) YAML.dump(doc) else # config errors are thrown in 'def swagger_format', no throw needed here JSON.pretty_generate(doc) diff --git a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb index 2a29cde..6561f8a 100644 --- a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb +++ b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb @@ -74,6 +74,8 @@ module Rswag it 'writes the swagger_doc(s) as yaml' do expect(File).to exist("#{swagger_root}/v1/swagger.json") expect { JSON.parse(File.read("#{swagger_root}/v1/swagger.json")) }.to raise_error(JSON::ParserError) + # Psych::DisallowedClass would be raised if we do not pre-process ruby symbols + expect { YAML.safe_load(File.read("#{swagger_root}/v1/swagger.json")) }.not_to raise_error end end From 2c0f3c939682dbd8706b4c4424af864590dde263 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 12:58:36 +0000 Subject: [PATCH 62/83] Fix invalid Swagger in YAML --- rswag-specs/lib/rswag/specs/swagger_formatter.rb | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb index d16aeb2..7a8687a 100644 --- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb +++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb @@ -48,14 +48,17 @@ module Rswag def pretty_generate(doc) if @config.swagger_format == :yaml - # NOTE: Yaml will quite happily embed ruby-only classes such as symbols. - # clean_doc = stringify(doc) - YAML.dump(doc) + YAML.dump(doc.deep_stringify_keys) else # config errors are thrown in 'def swagger_format', no throw needed here JSON.pretty_generate(doc) end end + def deep_stringify_hash_keys(doc) + + doc + end + def metadata_to_swagger(metadata) response_code = metadata[:response][:code] response = metadata[:response].reject { |k,v| k == :code } From eeb10266918ca52c6aa1e1e86fedbc3a7c1f65d4 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 13:13:02 +0000 Subject: [PATCH 63/83] Fix invalid Swagger in YAML values The original fix failed because though the Keys were now strings, some of the values for path variables were also symbols. Psych does have a safe_load which has a whitelist of classes but it does not have a safe_dump mode. We could have used deep_transform_values and manually converted the classes we did not want, but why risk a buggy implementation when JSON.generate works just fine? --- rswag-specs/lib/rswag/specs/swagger_formatter.rb | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb index 7a8687a..6e23350 100644 --- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb +++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb @@ -48,15 +48,16 @@ module Rswag def pretty_generate(doc) if @config.swagger_format == :yaml - YAML.dump(doc.deep_stringify_keys) + clean_doc = yaml_prepare(doc) + YAML.dump(clean_doc) else # config errors are thrown in 'def swagger_format', no throw needed here JSON.pretty_generate(doc) end end - def deep_stringify_hash_keys(doc) - - doc + def yaml_prepare(doc) + json_doc = JSON.pretty_generate(doc) + clean_doc = JSON.parse(json_doc) end def metadata_to_swagger(metadata) From dc161fe27530de043e19f415d1f6dbce63bc4550 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 13:57:47 +0000 Subject: [PATCH 64/83] Serve yaml files as yaml instead of converting them to json --- rswag-api/lib/rswag/api/middleware.rb | 19 +++++++++++++++---- rswag-api/spec/rswag/api/middleware_spec.rb | 4 ++-- .../rswag/ui/install/templates/rswag-ui.rb | 6 +++--- 3 files changed, 20 insertions(+), 9 deletions(-) diff --git a/rswag-api/lib/rswag/api/middleware.rb b/rswag-api/lib/rswag/api/middleware.rb index 7256794..637d42d 100644 --- a/rswag-api/lib/rswag/api/middleware.rb +++ b/rswag-api/lib/rswag/api/middleware.rb @@ -1,9 +1,10 @@ require 'json' require 'yaml' +require 'rack/mime' module Rswag module Api - class Middleware + class Middleware def initialize(app, config) @app = app @@ -17,14 +18,16 @@ module Rswag if env['REQUEST_METHOD'] == 'GET' && File.file?(filename) swagger = parse_file(filename) @config.swagger_filter.call(swagger, env) unless @config.swagger_filter.nil? + mime = Rack::Mime.mime_type(::File.extname(path), 'text/plain') + body = unload_swagger(filename, swagger) return [ '200', - { 'Content-Type' => 'application/json' }, - [ JSON.dump(swagger) ] + { 'Content-Type' => mime }, + [ body ] ] end - + return @app.call(env) end @@ -45,6 +48,14 @@ module Rswag def load_json(filename) JSON.parse(File.read(filename)) end + + def unload_swagger(filename, swagger) + if /\.ya?ml$/ === filename + YAML.dump(swagger) + else + JSON.dump(swagger) + end + end end end end diff --git a/rswag-api/spec/rswag/api/middleware_spec.rb b/rswag-api/spec/rswag/api/middleware_spec.rb index f784f25..3ff0594 100644 --- a/rswag-api/spec/rswag/api/middleware_spec.rb +++ b/rswag-api/spec/rswag/api/middleware_spec.rb @@ -87,8 +87,8 @@ module Rswag it 'returns contents of the swagger file' do expect(response.length).to eql(3) - expect(response[1]).to include( 'Content-Type' => 'application/json') - expect(response[2].join).to include('"title":"API V1"') + expect(response[1]).to include( 'Content-Type' => 'text/yaml') + expect(response[2].join).to include('title: API V1') end end end diff --git a/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb b/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb index 084a512..3a7fe3e 100644 --- a/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb +++ b/rswag-ui/lib/generators/rswag/ui/install/templates/rswag-ui.rb @@ -2,9 +2,9 @@ Rswag::Ui.configure do |c| # List the Swagger endpoints that you want to be documented through the swagger-ui # The first parameter is the path (absolute or relative to the UI host) to the corresponding - # JSON endpoint and the second is a title that will be displayed in the document selector - # NOTE: If you're using rspec-api to expose Swagger files (under swagger_root) as JSON endpoints, + # endpoint and the second is a title that will be displayed in the document selector + # NOTE: If you're using rspec-api to expose Swagger files (under swagger_root) as JSON or YAML endpoints, # then the list below should correspond to the relative paths for those endpoints - c.swagger_endpoint '/api-docs/v1/swagger.json', 'API V1 Docs' + c.swagger_endpoint '/api-docs/v1/swagger.yaml', 'API V1 Docs' end From 2d5da62bf1df7a0d9d4d681fc428ee0941c93643 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 14:02:31 +0000 Subject: [PATCH 65/83] CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bb1a888..b4a6374 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - New swagger_format config option for setting YAML output [#251](https://github.com/rswag/rswag/pull/251) ### Changed +- rswag-api will serve yaml files as yaml [#251](https://github.com/rswag/rswag/pull/251) ### Deprecated ### Removed ### Fixed From 4516ad4b7897a3234bc313334d786078a5c0fbb7 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 14:52:37 +0000 Subject: [PATCH 66/83] Update changelog and tweak readme --- CHANGELOG.md | 12 ++++++++++-- README.md | 26 ++++++++++++++++++++------ 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4a6374..f084c97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,14 +6,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added -- New swagger_format config option for setting YAML output [#251](https://github.com/rswag/rswag/pull/251) ### Changed -- rswag-api will serve yaml files as yaml [#251](https://github.com/rswag/rswag/pull/251) ### Deprecated ### Removed ### Fixed ### Security +## [2.2.0] - 2019-11-01 +### Added +- New swagger_format config option for setting YAML output [#251](https://github.com/rswag/rswag/pull/251) +### Changed +- rswag-api will serve yaml files as yaml [#251](https://github.com/rswag/rswag/pull/251) + +## [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) diff --git a/README.md b/README.md index bbf46e8..cfea9e4 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ 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. -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 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 JSON. 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. +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. And that's not all ... @@ -16,7 +16,7 @@ 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)|2.0|3.18.2| -|[2.1.1](https://github.com/rswag/rswag/tree/2.1.1)|2.0|3.18.2| +|[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| ## Getting Started ## @@ -123,6 +123,9 @@ Once you have an API that can describe itself in Swagger, you've opened the trea end ``` + There is also a generator which can help get you started `rails generate rspec:swagger API::MyController` + + 4. Generate the Swagger JSON file(s) ```ruby @@ -190,7 +193,7 @@ describe 'Blogs API' do end end ``` -*Note:* the OAI v3 may be released soon(ish?) and include a nullable property. This may have an effect on the need/use of custom extension to the draft. Do not use this property if you don't understand the implications. +*Note:* OAI v3 has a nullable property. Rswag will work to support this soon. This may have an effect on the need/use of custom extension to the draft. Do not use this property if you don't understand the implications. ### Global Metadata ### @@ -213,8 +216,8 @@ RSpec.configure do |config| basePath: '/api/v1' }, - 'v2/swagger.json' => { - swagger: '2.0', + 'v2/swagger.yaml' => { + openapi: '3.0.0', info: { title: 'API V2', version: 'v2', @@ -231,7 +234,7 @@ By default, the paths, operations and responses defined in your spec files will ```ruby # spec/integration/v2/blogs_spec.rb -describe 'Blogs API', swagger_doc: 'v2/swagger.json' do +describe 'Blogs API', swagger_doc: 'v2/swagger.yaml' do path '/blogs' do ... @@ -448,6 +451,17 @@ RSpec.configure do |config| config.swagger_dry_run = false end ``` + +### Running tests without documenting ### + +If you want to use Rswag for testing without adding it to you swagger docs, you can simply nullify the response metadata after the test run. + +```ruby +after do |example| + example.metadata[:response] = null +end +``` + ### Route Prefix for Swagger JSON Endpoints ### The functionality to expose Swagger files, such as those generated by rswag-specs, as JSON endpoints is implemented as a Rails Engine. As with any Engine, you can change it's mount prefix in _routes.rb_: From f8fb73fb149a6118e79efa723db9bf5f4865a3cc Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 15:03:40 +0000 Subject: [PATCH 67/83] Use a prebuilt ruby https://docs.travis-ci.com/user/reference/bionic/ Pre-installed Rubies: 2.3.8, 2.4.5, 2.5.3 and 2.6.3. --- .travis.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index 304c64c..028d624 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,11 +1,11 @@ language: ruby -dist: xenial +dist: bionic services: - xvfb rvm: - - 2.6.4 + - 2.6.3 env: - RAILS_VERSION=6.0.0 From 8d04646341f7c457e5d95ca741b3fcdf0faf4e48 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 15:09:21 +0000 Subject: [PATCH 68/83] Cache the correct directory --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 028d624..b4d1d20 100644 --- a/.travis.yml +++ b/.travis.yml @@ -19,7 +19,7 @@ addons: cache: directories: - - /home/travis/.rvm/gems/ruby-2.6.4 + - /home/travis/.rvm/gems/ruby-2.6.3 install: ./ci/build.sh From 8d8fc11e55f93d61926db89fa72a2a012a232114 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 15:35:51 +0000 Subject: [PATCH 69/83] correct ruby-version for travis --- .ruby-version | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ruby-version b/.ruby-version index 2714f53..ec1cf33 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.6.4 +2.6.3 From c108a8367cd856442886451b53e81a70e7b933cc Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 15:48:29 +0000 Subject: [PATCH 70/83] try conditional stages --- .travis.yml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index b4d1d20..324213b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,9 +17,7 @@ addons: - libqtwebkit-dev - libqtwebkit4 -cache: - directories: - - /home/travis/.rvm/gems/ruby-2.6.3 +cache: bundler install: ./ci/build.sh @@ -29,6 +27,7 @@ jobs: include: - stage: publish components script: 'cd rswag-api' + if: tags = true deploy: gemspec: rswag-api.gemspec provider: rubygems @@ -39,6 +38,7 @@ jobs: - stage: publish components script: 'cd rswag-specs' + if: tags = true deploy: gemspec: rswag-specs.gemspec provider: rubygems @@ -49,6 +49,7 @@ jobs: - stage: publish components script: 'cd rswag-ui' + if: tags = true deploy: gemspec: rswag-ui.gemspec provider: rubygems @@ -60,6 +61,7 @@ jobs: - stage: publish rswag script: 'cd rswag' + if: tags = true deploy: gemspec: rswag.gemspec provider: rubygems From dad99930aa66a28728c3646ad099bbf04def3bff Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 15:56:08 +0000 Subject: [PATCH 71/83] trigger build --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bbf46e8..7813841 100644 --- a/README.md +++ b/README.md @@ -522,7 +522,7 @@ end The swagger-ui provides several options for customizing it's behavior, all of which are documented here https://github.com/swagger-api/swagger-ui/tree/2.x#swaggerui. If you need to tweak these or customize the overall look and feel of your swagger-ui, then you'll need to provide your own version of index.html. You can do this with the following generator. ```ruby -rails g rswag:ui:custom +rails generate rswag:ui:custom ``` From 3dc0909a6a68ad090974b72564e06616d805a4c8 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 15:59:48 +0000 Subject: [PATCH 72/83] Use specific directory. We dont bundle to vendor/bundle --- .travis.yml | 4 +++- README.md | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index 324213b..d8599d1 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,7 +17,9 @@ addons: - libqtwebkit-dev - libqtwebkit4 -cache: bundler +cache: + directories: + - /home/travis/.rvm/gems/ruby-2.6.3 install: ./ci/build.sh diff --git a/README.md b/README.md index 7813841..bbf46e8 100644 --- a/README.md +++ b/README.md @@ -522,7 +522,7 @@ end The swagger-ui provides several options for customizing it's behavior, all of which are documented here https://github.com/swagger-api/swagger-ui/tree/2.x#swaggerui. If you need to tweak these or customize the overall look and feel of your swagger-ui, then you'll need to provide your own version of index.html. You can do this with the following generator. ```ruby -rails generate rswag:ui:custom +rails g rswag:ui:custom ``` From ccce4d63602d2c27e73316b6358be8b2c1c0d549 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 16:11:42 +0000 Subject: [PATCH 73/83] Fix travis.yml --- .travis.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index d8599d1..81348fe 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,7 +29,7 @@ jobs: include: - stage: publish components script: 'cd rswag-api' - if: tags = true + if: tag = true deploy: gemspec: rswag-api.gemspec provider: rubygems @@ -40,7 +40,7 @@ jobs: - stage: publish components script: 'cd rswag-specs' - if: tags = true + if: tag = true deploy: gemspec: rswag-specs.gemspec provider: rubygems @@ -51,7 +51,7 @@ jobs: - stage: publish components script: 'cd rswag-ui' - if: tags = true + if: tag = true deploy: gemspec: rswag-ui.gemspec provider: rubygems @@ -63,7 +63,7 @@ jobs: - stage: publish rswag script: 'cd rswag' - if: tags = true + if: tag = true deploy: gemspec: rswag.gemspec provider: rubygems From a46a5be3bb1a690f81616113e279986db86a1008 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 16:55:21 +0000 Subject: [PATCH 74/83] Use presence on tags in travis --- .travis.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index 81348fe..f987c52 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,7 +29,7 @@ jobs: include: - stage: publish components script: 'cd rswag-api' - if: tag = true + if: tag IS present deploy: gemspec: rswag-api.gemspec provider: rubygems @@ -40,7 +40,7 @@ jobs: - stage: publish components script: 'cd rswag-specs' - if: tag = true + if: tag IS present deploy: gemspec: rswag-specs.gemspec provider: rubygems @@ -51,7 +51,7 @@ jobs: - stage: publish components script: 'cd rswag-ui' - if: tag = true + if: tag IS present deploy: gemspec: rswag-ui.gemspec provider: rubygems @@ -63,7 +63,7 @@ jobs: - stage: publish rswag script: 'cd rswag' - if: tag = true + if: tag IS present deploy: gemspec: rswag.gemspec provider: rubygems From c904a32e51cbada44ce85d19661ea5c47c187000 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sat, 2 Nov 2019 17:06:17 +0000 Subject: [PATCH 75/83] Move constraint to less than rails 7 --- rswag-api/rswag-api.gemspec | 2 +- rswag-specs/rswag-specs.gemspec | 4 ++-- rswag-ui/rswag-ui.gemspec | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/rswag-api/rswag-api.gemspec b/rswag-api/rswag-api.gemspec index 3a14bb2..97e7a6a 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.1' + s.add_dependency 'railties', '>= 3.1', '< 7.0' end diff --git a/rswag-specs/rswag-specs.gemspec b/rswag-specs/rswag-specs.gemspec index e3ddaf3..ff46439 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.1' - s.add_dependency 'railties', '>= 3.1', '< 6.1' + s.add_dependency 'activesupport', '>= 3.1', '< 7.0' + s.add_dependency 'railties', '>= 3.1', '< 7.0' s.add_dependency 'json-schema', '~> 2.2' end diff --git a/rswag-ui/rswag-ui.gemspec b/rswag-ui/rswag-ui.gemspec index 1584470..d1ea0b1 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.1' - s.add_dependency 'railties', '>= 3.1', '< 6.1' + s.add_dependency 'actionpack', '>=3.1', '< 7.0' + s.add_dependency 'railties', '>= 3.1', '< 7.0' end From 3cd9d38e196bcb4d52af954b464f5b0d763ff1d0 Mon Sep 17 00:00:00 2001 From: Karl Johansson Date: Fri, 15 Nov 2019 14:34:07 +0100 Subject: [PATCH 76/83] Parameterize the pattern for test locations This commit allows users to specify search patterns when finding tests to swaggerize. Omitting the pattern parameter makes rswag search with the default patterns. A typical usecase for this feature is when you already have a test suite set up and you want to use rswag for generating swagger docs rather than high-coverage testing. Usage: rake rswag:specs:swaggerize PATTERN='/your_path..' --- README.md | 9 +++++++++ rswag-specs/lib/tasks/rswag-specs_tasks.rake | 6 ++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cfea9e4..ccedf25 100644 --- a/README.md +++ b/README.md @@ -339,6 +339,15 @@ end __NOTE__: If you do change this, you'll also need to update the rswag-api.rb initializer (assuming you're using rswag-api). More on this later. +### Input Location for Rspec Tests ### + +By default, rswag will search for integration tests in _spec/requests_, _spec/api_ and _spec/integration_. If you want to use tests from other locations, provide the PATTERN argument to rake: + +```ruby +# search for tests in spec/swagger +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. For example, you might have a standard response structure for all failed operations. Rather than repeating the schema in every operation spec, you can define it globally and provide a reference to it in each spec: diff --git a/rswag-specs/lib/tasks/rswag-specs_tasks.rake b/rswag-specs/lib/tasks/rswag-specs_tasks.rake index b7d276b..54412a2 100644 --- a/rswag-specs/lib/tasks/rswag-specs_tasks.rake +++ b/rswag-specs/lib/tasks/rswag-specs_tasks.rake @@ -5,7 +5,10 @@ namespace :rswag do desc 'Generate Swagger JSON files from integration specs' RSpec::Core::RakeTask.new('swaggerize') do |t| - t.pattern = 'spec/requests/**/*_spec.rb, spec/api/**/*_spec.rb, spec/integration/**/*_spec.rb' + t.pattern = ENV.fetch( + 'PATTERN', + 'spec/requests/**/*_spec.rb, spec/api/**/*_spec.rb, spec/integration/**/*_spec.rb' + ) # NOTE: rspec 2.x support if Rswag::Specs::RSPEC_VERSION > 2 && Rswag::Specs.config.swagger_dry_run @@ -18,4 +21,3 @@ namespace :rswag do end task :rswag => ['rswag:specs:swaggerize'] - From 4c613af2ba1a57240f2c4bdbd883e54c0deb1328 Mon Sep 17 00:00:00 2001 From: Karl Johansson Date: Fri, 15 Nov 2019 15:59:18 +0100 Subject: [PATCH 77/83] Allow tests to be run without generating docs By providing the 'document: false' metadata, tests will be run but no swagger documentation will be generated for the tagged example groups. It works on all kinds of example groups (responses, verbs, paths etc..). --- README.md | 28 ++++++++++++--- .../lib/rswag/specs/swagger_formatter.rb | 4 +++ .../rswag/specs/swagger_formatter_spec.rb | 36 +++++++++++++------ 3 files changed, 52 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index cfea9e4..d351f35 100644 --- a/README.md +++ b/README.md @@ -454,12 +454,30 @@ end ### Running tests without documenting ### -If you want to use Rswag for testing without adding it to you swagger docs, you can simply nullify the response metadata after the test run. - +If you want to use Rswag for testing without adding it to you swagger docs, you can provide the document tag: ```ruby -after do |example| - example.metadata[:response] = null -end +describe 'Blogs API' do + path '/blogs/{blog_id}' do + get 'Retrieves a blog' do + # documentation is now disabled for this response only + response 200, 'blog found', document: false do + ... +``` + +You can also reenable documentation for specific responses only: +```ruby +# documentation is now disabled +describe 'Blogs API', document: false do + path '/blogs/{blog_id}' do + get 'Retrieves a blog' do + # documentation is reenabled for this response only + response 200, 'blog found', document: true do + ... + end + + response 401, 'special case' do + ... + end ``` ### Route Prefix for Swagger JSON Endpoints ### diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb index 6e23350..0447034 100644 --- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb +++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb @@ -25,7 +25,11 @@ module Rswag metadata = notification.metadata end + # !metadata[:document] won't work, since nil means we should generate + # docs. + return if metadata[:document] == false return unless metadata.has_key?(:response) + swagger_doc = @config.get_swagger_doc(metadata[:swagger_doc]) swagger_doc.deep_merge!(metadata_to_swagger(metadata)) end diff --git a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb index 6561f8a..b0a53b5 100644 --- a/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb +++ b/rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb @@ -26,23 +26,37 @@ module Rswag { path_item: { template: '/blogs' }, operation: { verb: :post, summary: 'Creates a blog' }, - response: { code: '201', description: 'blog created' } + response: { code: '201', description: 'blog created' }, + document: document } end - it 'converts to swagger and merges into the corresponding swagger doc' do - expect(swagger_doc).to match( - paths: { - '/blogs' => { - post: { - summary: 'Creates a blog', - responses: { - '201' => { description: 'blog created' } + context 'with the document tag set to false' do + let(:document) { false } + + it 'does not update the swagger doc' do + expect(swagger_doc).to be_empty + end + end + + context 'with the document tag set to anything but false' do + # anything works, including its absence when specifying responses. + let(:document) { nil } + + it 'converts to swagger and merges into the corresponding swagger doc' do + expect(swagger_doc).to match( + paths: { + '/blogs' => { + post: { + summary: 'Creates a blog', + responses: { + '201' => { description: 'blog created' } + } } } } - } - ) + ) + end end end From 19e985a828011b2b961bc5a9c5e32f2cff51f85e Mon Sep 17 00:00:00 2001 From: Kabiru Mwenja Date: Mon, 6 Jan 2020 09:50:30 +0300 Subject: [PATCH 78/83] chore(rswag-ui): Organise basic auth files --- rswag-ui/lib/rswag/ui/basic_auth.rb | 25 +++++++++++++++++++++++++ rswag-ui/lib/rswag/ui/engine.rb | 25 +------------------------ 2 files changed, 26 insertions(+), 24 deletions(-) create mode 100644 rswag-ui/lib/rswag/ui/basic_auth.rb diff --git a/rswag-ui/lib/rswag/ui/basic_auth.rb b/rswag-ui/lib/rswag/ui/basic_auth.rb new file mode 100644 index 0000000..957ddfb --- /dev/null +++ b/rswag-ui/lib/rswag/ui/basic_auth.rb @@ -0,0 +1,25 @@ +require 'rack/auth/basic' + +class BasicAuth < ::Rack::Auth::Basic + def call(env) + return @app.call(env) unless env_matching_path + + super(env) + end + + private + + def env_matching_path + swagger_endpoints = Rswag::Ui.config.swagger_endpoints[:urls] + swagger_endpoints.find do |endpoint| + base_path = base_path(endpoint[:url]) + env_base_path = base_path(env['PATH_INFO']) + + base_path == env_base_path + end + end + + def base_path(url) + url.downcase.split('/')[1] + end +end diff --git a/rswag-ui/lib/rswag/ui/engine.rb b/rswag-ui/lib/rswag/ui/engine.rb index 962dc9f..c4cffae 100644 --- a/rswag-ui/lib/rswag/ui/engine.rb +++ b/rswag-ui/lib/rswag/ui/engine.rb @@ -1,28 +1,5 @@ require 'rswag/ui/middleware' - -class UiBasicAuth < ::Rack::Auth::Basic - def call(env) - return @app.call(env) unless env_matching_path - - super(env) - end - - private - - def env_matching_path - swagger_endpoints = Rswag::Ui.config.swagger_endpoints[:urls] - swagger_endpoints.find do |endpoint| - base_path = base_path(endpoint[:url]) - env_base_path = base_path(env['PATH_INFO']) - - base_path == env_base_path - end - end - - def base_path(url) - url.downcase.split('/')[1] - end -end +require 'rswag/ui/basic_auth' module Rswag module Ui From a43e6f65469c3220c17e44d93e73908c18f75cdb Mon Sep 17 00:00:00 2001 From: Kabiru Mwenja Date: Mon, 6 Jan 2020 10:55:43 +0300 Subject: [PATCH 79/83] fix(rswag-ui): Define BasicAuth in Rswag::Ui module --- rswag-ui/lib/rswag/ui/basic_auth.rb | 41 ++++++++++++++++++----------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/rswag-ui/lib/rswag/ui/basic_auth.rb b/rswag-ui/lib/rswag/ui/basic_auth.rb index 957ddfb..7bbd85d 100644 --- a/rswag-ui/lib/rswag/ui/basic_auth.rb +++ b/rswag-ui/lib/rswag/ui/basic_auth.rb @@ -1,25 +1,34 @@ +# frozen_string_literal: true + require 'rack/auth/basic' -class BasicAuth < ::Rack::Auth::Basic - def call(env) - return @app.call(env) unless env_matching_path +module Rswag + module Ui + # Extend Rack HTTP Basic Authentication, as per RFC 2617. + # @api private + # + class BasicAuth < ::Rack::Auth::Basic + def call(env) + return @app.call(env) unless env_matching_path - super(env) - end + super(env) + end - private + private - def env_matching_path - swagger_endpoints = Rswag::Ui.config.swagger_endpoints[:urls] - swagger_endpoints.find do |endpoint| - base_path = base_path(endpoint[:url]) - env_base_path = base_path(env['PATH_INFO']) + def env_matching_path + Rswag::Ui.config.swagger_endpoints[:urls].find do |endpoint| + base_path(endpoint[:url]) == env_base_path + end + end - base_path == env_base_path + def env_base_path + base_path(env['PATH_INFO']) + end + + def base_path(url) + url.downcase.split('/')[1] + end end end - - def base_path(url) - url.downcase.split('/')[1] - end end From e21f786926c5261893922001bf2c7c78369675a4 Mon Sep 17 00:00:00 2001 From: Chris Miller Date: Wed, 29 Jan 2020 16:28:06 -0800 Subject: [PATCH 80/83] fix(references): update reference to Rswag::Ui::BasicAuth and env_matching_path environment accessor --- rswag-ui/lib/rswag/ui/basic_auth.rb | 13 +++++-------- rswag-ui/lib/rswag/ui/engine.rb | 2 +- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/rswag-ui/lib/rswag/ui/basic_auth.rb b/rswag-ui/lib/rswag/ui/basic_auth.rb index 7bbd85d..ee42d36 100644 --- a/rswag-ui/lib/rswag/ui/basic_auth.rb +++ b/rswag-ui/lib/rswag/ui/basic_auth.rb @@ -9,23 +9,20 @@ module Rswag # class BasicAuth < ::Rack::Auth::Basic def call(env) - return @app.call(env) unless env_matching_path + return @app.call(env) unless env_matching_path(env) super(env) end private - def env_matching_path - Rswag::Ui.config.swagger_endpoints[:urls].find do |endpoint| - base_path(endpoint[:url]) == env_base_path + def env_matching_path(env) + path = base_path(env['PATH_INFO']) + Rswag::Ui.config.config_object[:urls].find do |endpoint| + base_path(endpoint[:url]) == path end end - def env_base_path - base_path(env['PATH_INFO']) - end - def base_path(url) url.downcase.split('/')[1] end diff --git a/rswag-ui/lib/rswag/ui/engine.rb b/rswag-ui/lib/rswag/ui/engine.rb index c4cffae..e90b4f2 100644 --- a/rswag-ui/lib/rswag/ui/engine.rb +++ b/rswag-ui/lib/rswag/ui/engine.rb @@ -11,7 +11,7 @@ module Rswag if Rswag::Ui.config.basic_auth_enabled c = Rswag::Ui.config - app.middleware.use UiBasicAuth do |username, password| + app.middleware.use Rswag::Ui::BasicAuth do |username, password| c.config_object[:basic_auth].values == [username, password] end end From 3046ea9f33ec88d3fdb13efc4a427d140921adc0 Mon Sep 17 00:00:00 2001 From: Brigitte Jellinek Date: Mon, 23 Mar 2020 07:10:23 +0100 Subject: [PATCH 81/83] fix README.md: dry_run goes into test.rb, not application.rb adding RSpec.configure to application.rb can lead to problems in production, where rspec may not be present. config/environments/test.rb avoids these problems. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5018d3a..1a9b306 100644 --- a/README.md +++ b/README.md @@ -454,7 +454,7 @@ end ``` You need to disable --dry-run option for Rspec > 3 -Add to application.rb: +Add to config/environments/test.rb: ```ruby RSpec.configure do |config| config.swagger_dry_run = false From cddb7ae614b7133e513f88410e53e1fa145746bd Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Fri, 27 Mar 2020 00:16:07 +0000 Subject: [PATCH 82/83] add preamble to contributing guide we wish to make it easier to know what to expect as a contributor. That is we want semantic versioning, and we want you to know that contributions are valuable, and that as a contributor you don't own anyone anything so there's no pressure. --- CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c22b355..0f25fff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,11 @@ # Contributing +🎉 Thanks for taking the time to contribute! 🎉 + +We put forward the philosophy put forward by the [react community](https://reactcommunity.org/) about ownership, responsibility and avoiding burnout. + +We also strive to achieve [semantic versioning](https://semver.org/) for this repo. + ## Fork, then clone the repo: ``` git clone git@github.com:rswag/rswag.git From b000c94ea0011ef0d0d891adedb4fc9500791809 Mon Sep 17 00:00:00 2001 From: Greg Myers Date: Sun, 29 Mar 2020 20:27:36 +0100 Subject: [PATCH 83/83] add output for swaggerize command by inheriting thhe base text formatter --- rswag-specs/lib/rswag/specs/swagger_formatter.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rswag-specs/lib/rswag/specs/swagger_formatter.rb b/rswag-specs/lib/rswag/specs/swagger_formatter.rb index 0447034..568f7e2 100644 --- a/rswag-specs/lib/rswag/specs/swagger_formatter.rb +++ b/rswag-specs/lib/rswag/specs/swagger_formatter.rb @@ -1,9 +1,10 @@ require 'active_support/core_ext/hash/deep_merge' +require 'rspec/core/formatters/base_text_formatter' require 'swagger_helper' module Rswag module Specs - class SwaggerFormatter + class SwaggerFormatter < ::RSpec::Core::Formatters::BaseTextFormatter # NOTE: rspec 2.x support if RSPEC_VERSION > 2