swagger-blocks 1.1.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b866c42150b355a3435ee64d3e614c8833f66e0
-  data.tar.gz: 25c4cce082108016db076e702d8800a04190a2e7
+  metadata.gz: a6055711e3ea9c391a362d51dab6494f1fb4c8e8
+  data.tar.gz: 03248ded0ff0ba04e55345a94ec0ce82d3e4134b
 SHA512:
-  metadata.gz: 43785e40a8cd10c442e7691cda08c23270218bbaa1de1a7ff96100ce2401230c36f4868bda1f6d3e13fc383dfda65f2a00510c291e697cf70ddcd9e3c18419b8
-  data.tar.gz: 6e9b4abc905314c968557731fd758e9cc28fda85c42e7cf389ab4b24a2caaadedb085717ab4c71e4c5f54dfb5e0118d2a2494104114348d2d690efcdebc7682c
+  metadata.gz: 344b4923bf905546cd1242854220f0da1b4cafc0510286e14c1fecb33fac05d7056218a0cede84afd989a2a277d9b7537d5d06964ba14ee3b9b2b9ff793f0537
+  data.tar.gz: e81f1506e5286e47168e83e65e5c2e130c108fc66805c383da4266c891c8dd13de5b9bbea01099c7da7d1273d9173716f7cfa87c16b6bcc4c8d86da15a0294df

data/README.md

@@ -45,6 +45,9 @@ class PetsController < ActionController::Base
     operation :get do
       key :description, 'Returns a single pet if the user has access'
       key :operationId, 'findPetById'
+      key :tags, [
+        'pet'
+      ]
       parameter do
         key :name, :id
         key :in, :path
@@ -75,6 +78,9 @@ class PetsController < ActionController::Base
         'application/json',
         'text/html',
       ]
+      key :tags, [
+        'pet'
+      ]
       parameter do
         key :name, :tags
         key :in, :query
@@ -116,6 +122,9 @@ class PetsController < ActionController::Base
       key :produces, [
         'application/json'
       ]
+      key :tags, [
+        'pet'
+      ]
       parameter do
         key :name, :pet
         key :in, :body
@@ -231,6 +240,14 @@ class ApidocsController < ActionController::Base
         key :name, 'MIT'
       end
     end
+    tags do
+      key :name, 'pet'
+      key :description, 'Pets operations'
+      externalDocs do
+        key :description, 'Find more info here'
+        key :url, 'https://swagger.io'
+      end
+    end
     key :host, 'petstore.swagger.wordnik.com'
     key :basePath, '/api'
     key :consumes, ['application/json']
@@ -261,6 +278,60 @@ That is the only line necessary to build the full [root Swagger object](https://
 
 Now, simply point Swagger UI at `/apidocs` and everything should Just Work™. If you change any of the Swagger block definitions, you can simply refresh Swagger UI to see the changes.
 
+#### Security handling
+
+To support Swagger's definitions for API key auth or OAuth2, use `security_definition` in your `swagger_root`:
+
+```Ruby
+  swagger_root do
+    key :swagger, '2.0'
+
+    # ...
+
+    security_definition :api_key do
+      key :type, :apiKey
+      key :name, :api_key
+      key :in, :header
+    end
+    security_definition :petstore_auth do
+      key :type, :oauth2
+      key :authorizationUrl, 'http://swagger.io/api/oauth/dialog'
+      key :flow, :implicit
+      scopes do
+        key 'write:pets', 'modify pets in your account'
+        key 'read:pets', 'read your pets'
+      end
+    end
+  end
+```
+
+You can then apply [security requirement objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityRequirementObject) to the entire `swagger_root`, or to individual operations:
+
+```Ruby
+  swagger_path '/pets/{id}' do
+    operation :get do
+
+      # ...
+
+      security do
+        key :api_key, []
+      end
+      security do
+        key :petstore_auth, ['write:pets', 'read:pets']
+      end
+    end
+  end
+```
+
+#### Writing JSON to a file
+
+If you are not serving the JSON directly and need to write it to a file for some reason, you can easily use `build_root_json` for that as well:
+
+```Ruby
+swagger_data = Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
+File.open('swagger.json', 'w') { |file| file.write(swagger_data.to_json) }
+```
+
 ### Swagger 1.2 example (Rails)
 
 See the [v1.2 docs](https://github.com/fotinakis/swagger-blocks/blob/master/README_v1_2.md).

data/README_v1_2.md

@@ -1,5 +1,7 @@
 # Swagger 1.2 example (Rails)
 
+**NOTE: this is old, you probably want to [use the latest syntax](https://github.com/fotinakis/swagger-blocks).**
+
 This is a simplified example based on the objects in the Petstore [Swagger Sample App](http://petstore.swagger.wordnik.com/#!/pet). For a more complex and complete example, see the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) file.
 
 Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.

data/lib/swagger/blocks.rb

@@ -400,6 +400,9 @@ module Swagger
     # v1.2: http://goo.gl/PvwUXj#516-scope-object
     class ScopeNode < Node; end
 
+    # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#scopes-object
+    class ScopesNode < Node; end
+
     # v1.2: http://goo.gl/PvwUXj#517-grant-types-object
     class GrantTypesNode < Node
       def implicit(&block)
@@ -551,9 +554,8 @@ module Swagger
     class SecuritySchemeNode < Node
       # TODO support ^x- Vendor Extensions
 
-      def scope(name, description)
-        self.data[:scopes] ||= {}
-        self.data[:scopes][name] = description
+      def scopes(&block)
+        self.data[:scopes] = Swagger::Blocks::ScopesNode.call(version: version, &block)
       end
     end
 

data/lib/swagger/blocks/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Blocks
-    VERSION = '1.1.1'
+    VERSION = '1.1.2'
   end
 end

data/spec/lib/swagger_v2_api_declaration.json

@@ -23,6 +23,22 @@
   "produces": [
     "application/json"
   ],
+  "securityDefinitions": {
+    "api_key": {
+      "type": "apiKey",
+      "name": "api_key",
+      "in": "header"
+    },
+    "petstore_auth": {
+      "type": "oauth2",
+      "authorizationUrl": "http://swagger.io/api/oauth/dialog",
+      "flow": "implicit",
+      "scopes": {
+        "write:pets": "modify pets in your account",
+        "read:pets": "read your pets"
+      }
+    }
+  },
   "tags": [
     {
       "name": "pet",
@@ -149,7 +165,18 @@
               "$ref": "#/definitions/ErrorModel"
             }
           }
-        }
+        },
+        "security": [
+          {
+            "api_key": []
+          },
+          {
+            "petstore_auth": [
+              "write:pets",
+              "read:pets"
+            ]
+          }
+        ]
       },
       "delete": {
         "description": "deletes a single pet based on the ID supplied",

data/spec/lib/swagger_v2_blocks_spec.rb

@@ -28,6 +28,20 @@ class PetControllerV2
     key :schemes, ['http']
     key :consumes, ['application/json']
     key :produces, ['application/json']
+    security_definition :api_key do
+      key :type, :apiKey
+      key :name, :api_key
+      key :in, :header
+    end
+    security_definition :petstore_auth do
+      key :type, :oauth2
+      key :authorizationUrl, 'http://swagger.io/api/oauth/dialog'
+      key :flow, :implicit
+      scopes do
+        key 'write:pets', 'modify pets in your account'
+        key 'read:pets', 'read your pets'
+      end
+    end
     tags do
       key :name, 'pet'
       key :description, 'Pets operations'
@@ -143,6 +157,12 @@ class PetControllerV2
           key :'$ref', :ErrorModel
         end
       end
+      security do
+        key :api_key, []
+      end
+      security do
+        key :petstore_auth, ['write:pets', 'read:pets']
+      end
     end
     operation :delete do
       key :description, 'deletes a single pet based on the ID supplied'
@@ -234,6 +254,9 @@ describe 'Swagger::Blocks v2' do
       expect(actual['paths']).to be
       expect(actual['paths']['/pets']).to be
       expect(actual['paths']['/pets']).to eq(data['paths']['/pets'])
+      expect(actual['paths']['/pets/{id}']).to be
+      expect(actual['paths']['/pets/{id}']['get']).to be
+      expect(actual['paths']['/pets/{id}']['get']).to eq(data['paths']['/pets/{id}']['get'])
       expect(actual['paths']).to eq(data['paths'])
       expect(actual['definitions']).to eq(data['definitions'])
       expect(actual).to eq(data)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger-blocks
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors:
 - Mike Fotinakis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-13 00:00:00.000000000 Z
+date: 2015-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler