Use presence on tags in travis

Improved yaml support

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,17 @@
+## Describe the bug
+A clear and concise description of what the bug is.
+
+## Steps to Test or Reproduce
+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.
+
+## Screenshots
+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.

.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.

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,15 @@
+## Problem
+A clear and concise description of what the problem is.
+
+## Solution
+A clear and concise description of what the solution is.
+
+### Related Issues
+Links to any related issues.
+
+### Checklist
+- [ ] Added tests
+- [ ] Changelog updated
+
+### Steps to Test or Reproduce
+Outline the steps to test or reproduce the PR here.

.ruby-version

@@ -1 +1 @@
-2.6.4
+2.6.3

.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
@@ -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
 
@@ -29,6 +29,7 @@ jobs:
   include:
     - stage: publish components
       script: 'cd rswag-api'
+      if: tag IS present
       deploy:
         gemspec: rswag-api.gemspec
         provider: rubygems
@@ -39,6 +40,7 @@ jobs:
 
     - stage: publish components
       script: 'cd rswag-specs'
+      if: tag IS present
       deploy:
         gemspec: rswag-specs.gemspec
         provider: rubygems
@@ -49,6 +51,7 @@ jobs:
 
     - stage: publish components
       script: 'cd rswag-ui'
+      if: tag IS present
       deploy:
         gemspec: rswag-ui.gemspec
         provider: rubygems
@@ -60,6 +63,7 @@ jobs:
 
     - stage: publish rswag
       script: 'cd rswag'
+      if: tag IS present
       deploy:
         gemspec: rswag.gemspec
         provider: rubygems

CHANGELOG.md

@@ -12,6 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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)

README.md

@@ -1,10 +1,11 @@
 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.
 
-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 ...
 
@@ -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.0.6](https://github.com/rswag/rswag/tree/2.0.6)|2.0|3.17.3|
+|[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 ##
@@ -26,14 +27,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
@@ -121,12 +123,17 @@ 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
     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 ##
@@ -186,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.
 <https://github.com/OAI/OpenAPI-Specification/issues/229#issuecomment-280376087>
 
 ### Global Metadata ###
@@ -209,8 +216,8 @@ RSpec.configure do |config|
       basePath: '/api/v1'
     },
 
-    'v2/swagger.json' => {
+    'v2/swagger.yaml' => {
-      swagger: '2.0',
+      openapi: '3.0.0',
       info: {
         title: 'API V2',
         version: 'v2',
@@ -227,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
   ...
@@ -444,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_:

rswag-api/lib/rswag/api/middleware.rb

@@ -1,4 +1,6 @@
 require 'json'
+require 'yaml'
+require 'rack/mime'
 
 module Rswag
   module Api
@@ -14,13 +16,15 @@ 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?
+          mime = Rack::Mime.mime_type(::File.extname(path), 'text/plain')
+          body = unload_swagger(filename, swagger)
 
           return [
             '200',
-            { 'Content-Type' => 'application/json' },
+            { 'Content-Type' => mime },
-            [ JSON.dump(swagger) ]
+            [ body ]
           ]
         end
 
@@ -29,9 +33,29 @@ module Rswag
 
       private
 
+      def parse_file(filename)
+        if /\.ya?ml$/ === 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
+
+      def unload_swagger(filename, swagger)
+        if /\.ya?ml$/ === filename
+          YAML.dump(swagger)
+        else
+          JSON.dump(swagger)
+        end
+      end
     end
   end
 end

rswag-api/spec/rswag/api/fixtures/swagger/v1/swagger.yml

@@ -0,0 +1,5 @@
+swagger: '2.0'
+info:
+  title: API V1
+  version: v1
+paths: {}

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' => 'text/yaml')
+            expect(response[2].join).to include('title: API V1')
+          end
+        end
       end
     end
   end

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' => {
+    'v1/swagger.yaml' => {
-      swagger: '2.0',
+      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

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

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]

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,20 @@ module Rswag
 
       private
 
+      def pretty_generate(doc)
+        if @config.swagger_format == :yaml
+          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 yaml_prepare(doc)
+        json_doc = JSON.pretty_generate(doc)
+        clean_doc = JSON.parse(json_doc)
+      end
+
       def metadata_to_swagger(metadata)
         response_code = metadata[:response][:code]
         response = metadata[:response].reject { |k,v| k == :code }

rswag-specs/lib/tasks/rswag-specs_tasks.rake

@@ -16,3 +16,6 @@ namespace :rswag do
     end
   end
 end
+
+task :rswag => ['rswag:specs:swaggerize']
+

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__)
 

rswag-specs/spec/rswag/specs/configuration_spec.rb

@@ -3,10 +3,12 @@ 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) }
+      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) }
 

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

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

rswag-specs/spec/rswag/specs/request_factory_spec.rb

@@ -3,7 +3,7 @@ require 'rswag/specs/request_factory'
 module Rswag
   module Specs
 
-    describe RequestFactory do
+    RSpec.describe RequestFactory do
       subject { RequestFactory.new(config) }
 
       before do

rswag-specs/spec/rswag/specs/response_validator_spec.rb

@@ -3,7 +3,7 @@ require 'rswag/specs/response_validator'
 module Rswag
   module Specs
 
-    describe ResponseValidator do
+    RSpec.describe ResponseValidator do
       subject { ResponseValidator.new(config) }
 
       before do

rswag-specs/spec/rswag/specs/swagger_formatter_spec.rb

@@ -4,7 +4,7 @@ require 'ostruct'
 module Rswag
   module Specs
 
-    describe SwaggerFormatter do
+    RSpec.describe SwaggerFormatter do
       subject { described_class.new(output, config) }
 
       # Mock out some infrastructure
@@ -53,14 +53,30 @@ 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
+          it 'writes the swagger_doc(s) to file' do
-          expect(File).to exist("#{swagger_root}/v1/swagger.json")
+            expect(File).to exist("#{swagger_root}/v1/swagger.json")
-          expect(File).to exist("#{swagger_root}/v2/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)
+            # 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
 
         after do

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
+  # 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,
+  # 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

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'

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

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

test-app/spec/rake/rswag_specs_swaggerize_spec.rb

@@ -1,7 +1,7 @@
 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
     TestApp::Application.load_tasks