rspec-rails-swagger 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b786f25e06ff3d37c343ea9a9156d215de7a75e3
-  data.tar.gz: 4d35f9fcde88c3434270c79ddb41db882a6827e5
+  metadata.gz: 7a2b47ce191c99f44fb347b30d0f008598b12333
+  data.tar.gz: ef2a2ba21b5ae8205d5fef54ba82f41433da7315
 SHA512:
-  metadata.gz: 301367639404276196630c3dd68748943e228664851d0d4e53695835e640d461c6a2ad227c14d9dee4ec097122ab261ce8afde0078b93bf7b6581973e954f980
-  data.tar.gz: b57370b15e66decde9ef4b19f20fe0877da65ed2fd76cc50bdab08c725106f2f8b69107542bce1e989064e7f36d56dc49730601f836804c3f49486855994ba19
+  metadata.gz: 8c6b22a14ed9e8500c79079b2df7752466ee655c6e68b12219538da0ded969bd3ed4025a912f3e2177c9ab6fcc66b25cc76abfb57fc97df470abafdd061900e5
+  data.tar.gz: 6ab205147771de49993331072bd1961ec81fe8a766b01adaffa7f4e13153f695900451fbffd192b906babcb798370c4a6c21a4df461a10b00e3f611e0f921b8b

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at drewish@katherinehouse.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+## Running tests
+
+The `make_site.sh` script will create a test site for a specific version of
+Rails and run the tests:
+```
+RAILS_VERSION=4.2.0
+./make_site.sh
+```
+
+Once the test site is created you can just re-run the tests:
+```
+bundle exec rspec
+```

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 andrew morton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,65 @@
+# RSpec Rails Swagger
+
+[![Build Status](https://travis-ci.org/drewish/rspec-rails-swagger.svg?branch=master)](https://travis-ci.org/drewish/rspec-rails-swagger)
+[![Code Climate](https://codeclimate.com/github/drewish/rspec-rails-swagger/badges/gpa.svg)](https://codeclimate.com/github/drewish/rspec-rails-swagger)
+
+This gem helps you generate Swagger docs by using RSpec to document the paths.
+You execute a command to run the tests and generate the `.json` output. Running
+the tests ensures that your API and docs are in agreement, and generates output
+that can be used as examples.
+
+The design of this was heavily influenced by the awesome [swagger_rails gem](https://github.com/domaindrivendev/swagger_rails).
+
+## Setup
+
+Add the gem to your Rails app's `Gemfile`:
+```rb
+group :development, :test do
+  gem 'rspec-rails-swagger'
+end
+```
+
+Update your bundle:
+```
+bundle install
+```
+
+If you don't have a `spec/rails_helper.rb` file:
+```
+rails generate rspec:install
+```
+
+Create the `spec/swagger_helper.rb` file:
+```
+rails generate rspec:swagger_install
+```
+
+## Documenting Your API
+
+Now you can edit `spec/swagger_helper.rb` and start filling in the top level
+Swagger documention, e.g. basePath, [definitions](http://swagger.io/specification/#definitionsObject),
+[parameters](http://swagger.io/specification/#parametersDefinitionsObject),
+[tags](http://swagger.io/specification/#tagObject), etc.
+
+You can use the generator to create a spec to documentation a controller:
+
+```
+rails generate rspec:swagger PostsController
+```
+
+That will create a `spec/requests/posts_spec.rb` file with the paths, operations
+and some default requests filled in. With the structure in place you should only
+need to add `before` calls to create records and then update the `let`s to
+return the appropriate values.
+
+## Generate the JSON
+
+To create the Swagger JSON files use the rake task:
+
+```
+bundle exec rake swagger
+```
+
+Now you can use Swagger UI or the renderer of your choice to display the
+formatted documentation. [swagger_engine](https://github.com/batdevis/swagger_engine)
+works pretty well and supports multiple documents.

data/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

data/lib/generators/rspec/swagger/swagger_generator.rb

@@ -0,0 +1,23 @@
+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

data/lib/generators/rspec/swagger/templates/spec.rb

@@ -0,0 +1,26 @@
+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: :path, type: :string
+<% end -%>
+    # ...and values used to make the requests.
+<% path_item[:params].each do |param| -%>
+    let(:<%= param %>) { '123' }
+<% end -%>
+
+<% end -%>
+<% path_item[:actions].each do | action, details | -%>
+    <%= action %>(summary: '<%= details[:summary] %>') do
+      response(200, description: 'successful') do
+        # You can add before/let blocks here to trigger the response code
+      end
+    end
+<% end -%>
+  end
+<% end -%>
+end

data/lib/generators/rspec/swagger_install/swagger_install_generator.rb

@@ -0,0 +1,13 @@
+require 'rails/generators'
+
+module Rspec
+  module Generators
+    class SwaggerInstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_swagger_helper
+        template 'spec/swagger_helper.rb'
+      end
+    end
+  end
+end

data/lib/generators/rspec/swagger_install/templates/spec/swagger_helper.rb

@@ -0,0 +1,18 @@
+require 'rspec/rails/swagger'
+require 'rails_helper'
+
+RSpec.configure do |config|
+  # Specify a root directory where the generated Swagger files will be saved.
+  config.swagger_root = Rails.root.to_s + '/swagger'
+
+  # Define one or more Swagger documents and global metadata for each.
+  config.swagger_docs = {
+    'v1/swagger.json' => {
+      swagger: '2.0',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      }
+    }
+  }
+end

data/lib/rspec/rails/swagger/formatter.rb

@@ -62,7 +62,7 @@ module RSpec
           when :path_item
             ["\n", metadata[:swagger_path_item][:path]]
           when :operation
-            ["\n  ", metadata[:swagger_operation][:method].to_s, "\t"]
+            ["\n  ", "%-8s" % metadata[:swagger_operation][:method]]
           end
         end
 
@@ -107,7 +107,7 @@ module RSpec
               operation[:parameters] = prepare_parameters(swagger_operation[:parameters])
             end
             operation.merge!(swagger_operation.slice(
-              :summary, :description, :externalDocs, :operationId,
+              :tags, :summary, :description, :externalDocs, :operationId,
               :consumes, :produces, :schemes, :deprecated, :security
             ))
           end

data/lib/rspec/rails/swagger/helpers.rb

@@ -174,6 +174,10 @@ module RSpec
             metadata[:swagger_operation][:produces] = mime_types
           end
 
+          def tags *tags
+            metadata[:swagger_operation][:tags] = tags
+          end
+
           def response status_code, attributes = {}, &block
             attributes.symbolize_keys!
 

data/lib/rspec/rails/swagger/request_builder.rb

@@ -20,11 +20,11 @@ module RSpec
         end
 
         def produces
-          metadata[:swagger_operation][:produces] || document[:produces]
+          Array(metadata[:swagger_operation][:produces]).presence || Array(document[:produces])
         end
 
         def consumes
-          metadata[:swagger_operation][:consumes] || document[:consumes]
+          Array(metadata[:swagger_operation][:consumes]).presence || Array(document[:consumes])
         end
 
         def parameters location = nil
@@ -52,7 +52,7 @@ module RSpec
           headers = {}
 
           # Match the names that Rails uses internally
-          headers['HTTP_ACCEPT'] = produces.join(';') if produces.present?
+          headers['HTTP_ACCEPT'] = produces.first if produces.present?
           headers['CONTENT_TYPE'] = consumes.first if consumes.present?
 
           # TODO: do we need to do some capitalization to match the rack

data/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

data/lib/rspec/rails/swagger/version.rb

@@ -3,7 +3,7 @@ module RSpec
     # Version information for RSpec Swagger.
     module Swagger
       module Version
-        STRING = '0.1.1'
+        STRING = '0.1.2'
       end
     end
   end

data/lib/rspec/rails/swagger.rb

@@ -4,6 +4,7 @@ require 'rspec/rails/swagger/document'
 require 'rspec/rails/swagger/formatter'
 require 'rspec/rails/swagger/helpers'
 require 'rspec/rails/swagger/request_builder'
+require 'rspec/rails/swagger/route_parser'
 require 'rspec/rails/swagger/version'
 
 module RSpec
@@ -16,6 +17,9 @@ module RSpec
           rake_tasks do
             load 'rspec/rails/swagger/tasks/swagger.rake'
           end
+          generators do
+            require "generators/rspec/swagger/swagger_generator.rb"
+          end
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rails-swagger
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - andrew morton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-28 00:00:00.000000000 Z
+date: 2016-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -44,12 +44,22 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- lib/generators/rspec/swagger/USAGE
+- lib/generators/rspec/swagger/swagger_generator.rb
+- lib/generators/rspec/swagger/templates/spec.rb
+- lib/generators/rspec/swagger_install/swagger_install_generator.rb
+- lib/generators/rspec/swagger_install/templates/spec/swagger_helper.rb
 - lib/rspec/rails/swagger.rb
 - lib/rspec/rails/swagger/configuration.rb
 - lib/rspec/rails/swagger/document.rb
 - lib/rspec/rails/swagger/formatter.rb
 - lib/rspec/rails/swagger/helpers.rb
 - lib/rspec/rails/swagger/request_builder.rb
+- lib/rspec/rails/swagger/route_parser.rb
 - lib/rspec/rails/swagger/tasks/swagger.rake
 - lib/rspec/rails/swagger/version.rb
 homepage: https://github.com/drewish/rspec-rails-swagger