rspec-rails-swagger 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0a916826de8e3e0b5f89296dcd78ca114356c106
-  data.tar.gz: e709fb01df49194a494f20e6b26a47958ae5d409
+  metadata.gz: ca8afd22d7d94c39871ce1136dfcc65f726df7fa
+  data.tar.gz: 8f42d67783da7d18d2bb6bd93ed4e86d19a6d636
 SHA512:
-  metadata.gz: daca2e677f67f13e83259c5cfae1046c033a6bb3dd82853f2d0f6455c5d49de8ea57026531692d98d9988914c8752bf8daf36869494c33bd2353c0b6e16357ce
-  data.tar.gz: cc2bcb1103465c99da748a33b0b18a3bf17745a15ecaef02e40a92905a1918f132d53f3e16ea687a492a47da5df69c6f60e02147422cadac18b4089e3d923ef2
+  metadata.gz: eddec5fcd5449d1cd397cf6684e89f47769fafde43d66d455ca7f46e03ac51306a2b648fe3465c97583957818244a55ee77802d3b2285fa3aeb4c6fa9b847f9e
+  data.tar.gz: 483a7470fa969fe6dfcfc48f08231309b63e46eb6b1da5e075b236d95e14841349527b94fe3df38ac8af14c1fa94c35984861f0a6681c0438dd24e7403441317

data/README.md

@@ -63,3 +63,186 @@ 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.
+
+## RSpec DSL
+
+The DSL follows the hierachy of the Swagger Schema:
+
+- [Paths Object](http://swagger.io/specification/#paths-object-29)
+  - [Path Item Object](http://swagger.io/specification/#path-item-object-32)
+    - [Parameter Object](http://swagger.io/specification/#parameter-object-44)s (Optional)
+    - [Operation Object](http://swagger.io/specification/#operation-object-36)
+      - [Parameter Object](http://swagger.io/specification/#parameter-object-44)s (Optional)
+      - [Responses Object](http://swagger.io/specification/#responses-object-54)
+        - [Response Object](http://swagger.io/specification/#response-object-58)
+          - [Example Object](http://swagger.io/specification/#example-object-65)s (Optional)
+
+Here's an example of a spec with comments to for the corresponding objects:
+
+```rb
+require 'swagger_helper'
+
+# Paths Object
+RSpec.describe "Posts Controller", type: :request do
+  before { Post.new.save }
+
+  # Path Item Object
+  path '/posts' do
+    # Operation Object
+    operation "GET", summary: "fetch list" do
+      # Response Object
+      response 200, description: "successful"
+    end
+  end
+
+  # Path Object
+  path '/posts/{post_id}' do
+    # Parameter Object
+    parameter "post_id", {in: :path, type: :integer}
+    let(:post_id) { 1 }
+
+    # Operation Object
+    get summary: "fetch item" do
+      # Response Object
+      response 200, description: "success"
+    end
+  end
+```
+
+
+### Paths Object
+These methods are available inside of an RSpec contexts with the `type: :request` tag.
+
+#### `path(template, attributes = {}, &block)`
+Defines a new Path Item.
+
+### Path Item Object
+These methods are available inside of blocks passed to the `path` method.
+
+#### `operation(method, attributes = {}, &block)`
+Defines a new Operation Object. The `method` is case insensitive.
+
+#### `delete(attributes = {}, &block)`
+Alias for `operation(:delete, attributes, block)`.
+
+#### `get(attributes = {}, &block)`
+Alias for `operation(:get, attributes, block)`.
+
+#### `head(attributes = {}, &block)`
+Alias for `operation(:head, attributes, block)`.
+
+#### `options(attributes = {}, &block)`
+Alias for `operation(:options, attributes, block)`.
+
+#### `patch(attributes = {}, &block)`
+Alias for `operation(:patch, attributes, block)`.
+
+#### `post(attributes = {}, &block)`
+Alias for `operation(:post, attributes, block)`.
+
+#### `put(attributes = {}, &block)`
+Alias for `operation(:put, attributes, block)`.
+
+
+### Parameters
+These methods are available inside of blocks passed to the `path` or `operation` method.
+
+#### `parameter(name, attributes = {})`
+Defines a new Parameter Object. You can define the parameter inline:
+```rb
+parameter :callback_url, in: :query, type: :string, required: true
+```
+
+Or, via reference:
+```rb
+parameter ref: "#/parameters/site_id"
+```
+
+Values for the parameters are set using `let`:
+```rb
+post summary: "create" do
+  parameter "body", in: :body, schema: { foo: :bar}
+  let(:body) { { post: { title: 'asdf', body: "blah" } } }
+  # ...
+end
+```
+
+
+### Operation Object
+These methods are available inside of blocks passed to the `operation` method.
+
+#### `consumes(*mime_types)`
+Use this to add MIME types that are specific to the operation. They will be merged
+with the Swagger Object's consumes field.
+```rb
+consumes 'application/json', 'application/xml'
+```
+
+#### `produces(*mime_types)`
+Use this to add MIME types that are specific to the operation. They will be merged
+with the Swagger Object's consumes field.
+```rb
+produces 'application/json', 'application/xml'
+```
+
+#### `response(status_code, attributes = {}, &block)`
+Defines a new Response Object. `status_code` must be between 1 and 599. `attributes`
+must include a `description`.
+
+#### `tags(*tags)`
+Adds operation specific tags.
+```rb
+tags :accounts, :pets
+```
+
+You can also provide tags through the RSpec context block and/or `path` method:
+```rb
+RSpec.describe "Sample Requests", type: :request, tags: [:context_tag] do
+  path '/posts', tags: ['path_tag'] do
+    operation "GET", summary: "fetch list" do
+      produces 'application/json'
+      tags 'operation_tag'
+
+      response(200, {description: "successful"})
+    end
+  end
+end
+```
+These tags will be merged with those of the operation. The `GET /posts` operation
+in this example will be tagged with `["context_tag", "path_tag", "operation_tag"]`.
+
+
+### Response Object
+These methods are available inside of blocks passed to the `response` method.
+
+#### `capture_example()`
+This method will capture the response body from the test and create an Example
+Object for the Response.
+
+You could also set this in an RSpec context block if you'd like examples for
+multiple operations or paths:
+```rb
+describe 'Connections', type: :request, capture_examples: true do
+  # Any requests in this block will capture example responses
+end
+```
+
+#### `schema(definition)`
+Sets the schema field for the Response Object. You can define it inline:
+```rb
+schema(
+  type: :array,
+  items: {
+    type: :object,
+    properties: {
+      id: { type: :string },
+      name: { type: :string },
+    },
+  }
+)
+```
+
+Or, by reference:
+```rb
+schema ref: '#/definitions/Account'
+```

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

@@ -42,13 +42,16 @@ module RSpec
             attributes.symbolize_keys!
 
             raise ArgumentError, "Path must start with a /" unless template.starts_with?('/')
-
             #TODO template might be a $ref
             meta = {
               swagger_object: :path_item,
               swagger_document: attributes[:swagger_document] || RSpec.configuration.swagger_docs.keys.first,
-              swagger_path_item: {path: template}
+              swagger_path_item: {path: template},
             }
+            # Merge tags passed into the path with those from parent contexts.
+            if attributes[:tags]
+              meta[:tags] = (metadata.try(:[], :tags) || []) + attributes[:tags]
+            end
             describe(template, meta, &block)
           end
         end
@@ -58,6 +61,12 @@ module RSpec
 
           def operation method, attributes = {}, &block
             attributes.symbolize_keys!
+            # Include tags from parent contexts so you can tag all the paths
+            # in a controller at once.
+            if metadata.try(:[], :tags).present?
+              attributes[:tags] ||= []
+              attributes[:tags] += metadata[:tags]
+            end
 
             method = method.to_s.downcase
             validate_method! method
@@ -175,7 +184,8 @@ module RSpec
           end
 
           def tags *tags
-            metadata[:swagger_operation][:tags] = tags
+            metadata[:swagger_operation][:tags] ||= []
+            metadata[:swagger_operation][:tags] += tags
           end
 
           def response status_code, attributes = {}, &block

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.3'
+        STRING = '0.1.4'
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rails-swagger
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - andrew morton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-21 00:00:00.000000000 Z
+date: 2017-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails