swagger-blocks 1.3.4 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e1f287d8e209522490c3d90b62948e11902c2926
-  data.tar.gz: 0d22ea28d1a2370ae8d896709b4ea52f3e66c221
+  metadata.gz: cdfadc9db4d5a4357533c00d7c1cb23d281d41f6
+  data.tar.gz: 06820847ade582beb6525e9d3bb9ca253ec0d161
 SHA512:
-  metadata.gz: aacf4e7ca9eb945bda88b89d3bdf4869130a63f5667caf305efcefd4658b973faa112e695d24aa43942ad68843db120c6399817f8598a16688dcfd96cd14dcaa
-  data.tar.gz: ce5b0633b5e74fe5cd6a2e4971d0086ee5089d8b7b266677ed42c16e1c3754eb3562ead1e4b1a892979b25bde6d72339b900472766f6d5cf87765d3a790ba4ac
+  metadata.gz: a8945bccc9050739d17f83c2b673fd85cba4b02ed21471e5bc361473779ee138f24aa1fff98095de83579e66b3df0d9e2a8a36b7fd2cb3bb4d4117c108901b65
+  data.tar.gz: 42f9773eb3c9a71f2851b7a7eeed46d6819130b168c44fa398f23cbbc510c31efe66e13cbfc38982ab11c8a26f2d8f3947831a600e2c6432efd35a1f9f23af84

data/README.md

@@ -331,6 +331,31 @@ The `key` block simply takes the value you give and puts it directly into the fi
   key :foo, {some_complex: {nested_object: true}}
 ```
 
+#### Parameter referencing
+
+It is possible to reference parameters rather than explicitly define them in every action in which they are used.
+
+To define a reusable parameter, declare it within `swagger_root`
+To reference the parameter, call it within a `swagger_path` or `operation` node
+
+```ruby
+swagger_root do
+  key :swagger, '2.0'
+  # ...
+  parameter :species do
+    key :name, :species
+    key :description, 'Species of this pet'
+  end
+end
+
+swagger_path '/pets/' do
+  operation :post do
+    parameter :species
+    # ...
+  end
+end
+```
+
 #### Inline keys
 
 It is possible to omit numerous `key` calls using inline hash keys on any block.
@@ -381,6 +406,39 @@ def build_and_override_root_json(overrides = {})
 end
 ```
 
+#### Reducing boilerplate
+
+To create reusable parameters, please see [parameter referencing](#parameter-referencing).
+
+Most APIs have some common responses for 401s, 404s, etc. Rather than declaring these responses over and over, you can create a reusable module.
+
+```ruby
+module SwaggerResponses
+  module AuthenticationError
+    def self.extended(base)
+      base.response 401 do
+        key :description, 'not authorized'
+        schema do
+          key :'$ref', :AuthenticationError
+        end
+      end
+    end
+  end
+end
+```
+
+Now, you just need to extend it:
+
+```ruby
+operation :post do
+  extend SwaggerResponses::AuthenticationError
+  # ...
+  response 200 do
+    # ...
+  end
+end
+```
+
 ### Swagger 1.2 example (Rails)
 
 See the [v1.2 docs](https://github.com/fotinakis/swagger-blocks/blob/master/README_v1_2.md).
@@ -413,6 +471,7 @@ Throw a ★ on it! :)
 
 ## Release notes
 
+* v1.4.0: Allow parameters to be defined once in swagger_root and reused.
 * v1.3.4: Fix support for fully-qualified URIs in `$ref` values.
 * v1.3.3: Bugfix to allow `parameter` inside `swagger_path`.
 * v1.3.2: Bugfix to allow `property` inside `items` for rare extended schema uses.

data/lib/swagger/blocks.rb

@@ -501,6 +501,8 @@ module Swagger
       end
 
       def parameter(inline_keys = nil, &block)
+        inline_keys = {'$ref' => "#/parameters/#{inline_keys}"} if inline_keys.is_a?(Symbol)
+
         self.data[:parameters] ||= []
         self.data[:parameters] << Swagger::Blocks::ParameterNode.call(version: version, inline_keys: inline_keys, &block)
       end
@@ -509,8 +511,9 @@ module Swagger
     # v1.2: http://goo.gl/PvwUXj#523-operation-object
     # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object
     class OperationNode < Node
-
       def parameter(inline_keys = nil, &block)
+        inline_keys = {'$ref' => "#/parameters/#{inline_keys}"} if inline_keys.is_a?(Symbol)
+
         self.data[:parameters] ||= []
         self.data[:parameters] << Swagger::Blocks::ParameterNode.call(version: version, inline_keys: inline_keys, &block)
       end

data/lib/swagger/blocks/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Blocks
-    VERSION = '1.3.4'
+    VERSION = '1.4.0'
   end
 end

data/spec/lib/swagger_v2_api_declaration.json

@@ -49,6 +49,14 @@
       }
     }
   ],
+  "parameters": {
+    "species": {
+      "name": "species",
+      "in": "body",
+      "description": "Species of this pet",
+      "type": "string"
+    }
+  },
   "paths": {
     "/pets": {
       "get": {
@@ -114,6 +122,9 @@
             "schema": {
               "$ref": "#/definitions/PetInput"
             }
+          },
+          {
+            "$ref": "#/parameters/species"
           }
         ],
         "responses": {
@@ -178,6 +189,41 @@
           }
         ]
       },
+      "put": {
+        "description": "Update a pet in the store.",
+        "operationId": "updatePet",
+        "produces": [
+          "application/json"
+        ],
+        "parameters": [
+          {
+            "name": "pet",
+            "in": "body",
+            "description": "Pet to update in the store",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/PetInput"
+            }
+          },
+          {
+            "$ref": "#/parameters/species"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "pet response",
+            "schema": {
+              "$ref": "#/parameters/Pet"
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "schema": {
+              "$ref": "http://example.com/schema.json#/definitions/ErrorModel"
+            }
+          }
+        }
+      },
       "delete": {
         "description": "deletes a single pet based on the ID supplied",
         "operationId": "deletePet",

data/spec/lib/swagger_v2_blocks_spec.rb

@@ -44,6 +44,12 @@ class PetControllerV2
         key :url, 'https://swagger.io'
       end
     end
+    parameter :species do
+      key :name, :species
+      key :in, :body
+      key :description, 'Species of this pet'
+      key :type, :string
+    end
   end
 
   swagger_path '/pets' do
@@ -105,6 +111,7 @@ class PetControllerV2
           key :'$ref', :PetInput
         end
       end
+      parameter :species
       response 200 do
         key :description, 'pet response'
         schema do
@@ -129,6 +136,37 @@ class PetControllerV2
       key :type, :integer
       key :format, :int64
     end
+    operation :put do
+      key :description, 'Update a pet in the store.'
+      key :operationId, 'updatePet'
+      key :produces, [
+        'application/json'
+      ]
+      parameter do
+        key :name, :pet
+        key :in, :body
+        key :description, 'Pet to update in the store'
+        key :required, true
+        schema do
+          key :'$ref', :PetInput
+        end
+      end
+
+      parameter :species
+
+      response 200 do
+        key :description, 'pet response'
+        schema do
+          # Wrong form here, but checks that #/ strings are not transformed.
+          key :'$ref', '#/parameters/Pet'
+        end
+      end
+      response :default, description: 'unexpected error' do
+        schema do
+          key :'$ref', 'http://example.com/schema.json#/definitions/ErrorModel'
+        end
+      end
+    end
     operation :get do
       key :description, 'Returns a user based on a single ID, if the user does not have access to the pet'
       key :operationId, 'findPetById'
@@ -270,7 +308,6 @@ describe 'Swagger::Blocks v2' do
     it 'is idempotent' do
       swaggered_classes = [PetControllerV2, PetV2, ErrorModelV2]
       actual = JSON.parse(Swagger::Blocks.build_root_json(swaggered_classes).to_json)
-      actual = JSON.parse(Swagger::Blocks.build_root_json(swaggered_classes).to_json)
       data = JSON.parse(RESOURCE_LISTING_JSON_V2)
       expect(actual).to eq(data)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger-blocks
 version: !ruby/object:Gem::Version
-  version: 1.3.4
+  version: 1.4.0
 platform: ruby
 authors:
 - Mike Fotinakis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-27 00:00:00.000000000 Z
+date: 2016-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.6.7
 signing_key: 
 specification_version: 4
 summary: Define and serve live-updating Swagger JSON for Ruby apps.