sinatra-swagger 0.2.0 → 0.2.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MjY0OWY2MzkyM2NiOWJhNWUxZjZiNjkwODhhMTgxNDkzMjBiNzI1NA==
+    ZDNkNzU3NDI5MDI2YWFkZjQwMTU3NTQ4OTJiODgxZGJiZWRkMTQ5Mg==
   data.tar.gz: !binary |-
-    NTcwYmUxZGNhZTg5OTkwMzc1Y2YwOWYxYzBmNDQ2ZTQ4OGE2MjY3Ng==
+    YjgzOWE5YjkwNjcwMmQyMDk2ZTlhMDVkNTRiM2Y4OGFmYWE1MmI5OA==
 SHA512:
   metadata.gz: !binary |-
-    OTFkMjcyNGFjYjJhZDlkMWIyMTA4OGRmNjNjMzI2NWJmMGNiY2I0NTkxYTlk
-    MGY5NTI3ZDRiMTgwZDM0ZmUwMmVkMDdiNzZmMDAwZWQ3NzU1YjVhZTFhMGU1
-    ZjAzZmU2MzRiNTZkOTI2ZTE1OTY1ZTc3NTk5MWQ4YzU0ZTFjMDQ=
+    OTRiNWI5NjgxMmY1MGE0ZmFlMTFlYWY2YTE4YmFkY2RjOTU3ZDBkMDkwMGNl
+    NjBmODJlNTM2M2VmMThkNjE3YjYwY2M3OTIwZDllMDc0YWViZGFlMjk2ODA1
+    ODE1MjFjMzRiYjQwNTFiYzhiYWMyMzYxNTYwYmFmN2U2OGU2MWQ=
   data.tar.gz: !binary |-
-    ZWFkNGI4Y2EyYWEzOTU0ZjJkNjExMDEyNWNhNWNmMmE3ZGMyYWMxNDllOWE1
-    YjdjOGI5NjJjODVlZWJjZDQ2NmYzNjdlM2E3M2M2ZWMyM2ZhZDlkYjQ5ODQ0
-    ZWIxYjZhZTQ2NjQ2M2EzNzM3MmVlZDNiM2Q4ZmMzZTM5YzI0NWY=
+    YWQ4MWU4MjUxZGY5OWJlMDE0MmM3Y2E4MGVlYzE0MDczOGVlNjQ0YmMyNjEx
+    ODAxYWFhOTRiYTEzODYxNjhlMTMxNzBiNjgxNWYzYmZjZGQ0Y2IzZGU2MDhk
+    MWI5MGY1NDlhYjk1YjVmNDY2OGUyNTExMDE2YjJhMWE4ZmZhNTU=

data/README.md

@@ -1,3 +1,105 @@
 # Sinatra::Swagger
 
-Helper methods for accesing your swagger documentation from within your sinatra routes.
+Extensions & helper methods for accesing your swagger documentation from within your sinatra routes.
+
+This library is in the *very* early stages of development, there will be 'obvious' features that are missing and wild inefficiencies, but please feel free to file issues/enhancements if there's anything you think would be useful.
+
+## Param Validator
+
+This extension will use the `parameters` component of the route being accessed from your Swagger document to type cast your incoming parameters and raise `400` errors if any are incorrect:
+
+### An example
+
+Your swagger 2.0 documentation, in the root of your project at `swagger/search.yaml`, might have some of these components:
+
+```yaml
+swagger: 2.0
+paths:
+  /search/{type}:
+    get:
+      parameters:
+        - name: type
+          in: path
+          description: Type of object to search for
+          required: true
+        - name: q
+          in: query
+          type: string
+          required: true
+        - name: limit
+          in: query
+          type: integer
+          minimum: 1
+          required: false
+          default: 20
+```
+
+You would load that in your sinatra application like this:
+
+```ruby
+require "sinatra/base"
+require "sinatra/swagger"
+
+class Search < Sinatra::Base
+  register Sinatra::Swagger::ParamValidator
+  swagger "swagger/search.yaml"
+
+  get "/search/*" do
+    # Sinatra::Swagger has pulled out the 'type' from the path
+    search_type = params['type']
+    # Sinatra::Swagger has ensured limit is integer-like, is one or bigger, and will be set to 20 if not given by the user
+    limit = params['limit']
+
+    swagger_spec # => is the hash from the spec at `paths./search/{type}.get`
+  end
+end
+```
+
+For now, if you were to request `/search/books` (ie. no required 'q' param) or `/search/books?q=penumbra&limit=p` then a `before` hook would catch the error and return a `400` with a JSON description of the issue.
+
+You can override what happens when an invalidity is encountered by overriding the helper method `invalid_params` which takes a hash of invalidities in the form `param_name => issue_description_as_symbol`.
+
+## Spec Enforcer
+
+While you're developing it can be really helpful to know that the output of your endpoints matches your spec. The spec enforcer will raise an exception if the data you're sending to the user doesn't conform to your swagger declared schema (if there is one).
+
+Your Swagger 2.0 doc at `swagger/shows.yaml` might have some bits that look like this:
+
+```yaml
+swagger: 2.0
+paths:
+  /shows/{showId}:
+    responses:
+      200:
+        schema:
+          title: Details describing a post
+          type: object
+          required:
+            - name
+          additionalProperties: false
+          properties:
+            name:
+              type: string
+```
+
+You could reference it like this:
+
+```ruby
+require "sinatra/base"
+require "sinatra/swagger"
+
+class Search < Sinatra::Base
+  register Sinatra::Swagger::SpecEnforcer unless production?
+  swagger "swagger/shows.yaml"
+
+  get "/shows/*" do
+    {
+      title: "This isn't a schema-valid response"
+    }.to_json
+  end
+end
+```
+
+The `after` hook will check the response body and will run the schema validation and raise a `JSON::Schema::ValidationError` exception as the output doesn't match the schema.
+
+In order to not be restrictive, if the output doesn't look like JSON or if there's no schema defined, then no action will be taken and the body will be sent to the client.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/sinatra/swagger/param_validator.rb

@@ -6,6 +6,20 @@ module Sinatra
       def self.registered(app)
         app.register Swagger::SwaggerLinked
 
+        app.helpers do
+          def invalid_params(invalidities)
+            content_type :json
+            halt(
+              400,
+              {
+                error: 'invalid_params',
+                developerMessage: 'Some of the given parameters were invalid according to the Swagger spec.',
+                invalidities: invalidities
+              }.to_json
+            )
+          end
+        end
+
         app.before do
           next if swagger_spec.nil?
           _, captures, spec = swagger_spec.values
@@ -45,7 +59,7 @@ module Sinatra
             nil
           }.compact]
 
-          halt 400, invalidities.to_json if invalidities.any?
+          invalid_params(invalidities) if invalidities.any?
         end
       end
     end

data/lib/sinatra/swagger/spec_enforcer.rb

@@ -1,4 +1,4 @@
-require "sinatra/swagger/param_validator"
+require "sinatra/swagger/swagger_linked"
 
 module Sinatra
   module Swagger

data/lib/sinatra/swagger.rb

@@ -1,2 +1,3 @@
 require "sinatra/swagger/version"
+require "sinatra/swagger/param_validator"
 require "sinatra/swagger/spec_enforcer"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-swagger
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - JP Hastings-Spital
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-13 00:00:00.000000000 Z
+date: 2015-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json-schema