swaggable 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e59f7b20f75ff1ecfcf7d6b3533163481aad335
-  data.tar.gz: bf2b29d46c656ab268dab1b577bea82aa00d5ef6
+  metadata.gz: 6f8d7d4f89aa6aa7a1e59f301405bc5b59243bc1
+  data.tar.gz: ee74ad314bbcfa0d5348a38545524cac1630456a
 SHA512:
-  metadata.gz: d38ea707dab9b2ab8040a32ae9c4fd718d3b3e0a7e128c54897659052a629719c779dab658ed6a4259fab6b81bd4ea18937791e77c10364af59ce63bda86b0d7
-  data.tar.gz: 49008f292dae3193e1bdbc8ec492e775fc633f89587a28a171f6ac56379a391f4a4dd55ea70d4b49c6768e9813dd690238ae779ed74b3fa78c7e078b714a01fc
+  metadata.gz: 9333877ec1e0a9f1e0c65cb5c5ecd28005ca454a807ff071747df5a143bb1fdfa8591d9dd82afc48f96fabd45d24232b7de06f4ca3d9d1f3d3869f45945fcad6
+  data.tar.gz: e21ae9c163049d6cd6da2e95f9c1d9629b847df05f27b3adf81159e40b398428c47be7cb24b1c81bb7cdd7a21a4602a26b92d83ab636635764b4a09bd9e0276b

data/.gitignore

@@ -1,2 +1,5 @@
 Gemfile.lock
 .yardoc
+*.gem
+coverage
+

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - 2.0.0
+  - 2.1.6
+  - 2.2.2
+  - rbx-2
+cache: bundler
+addons:
+  code_climate:
+    repo_token: 53088c47bea470645e73f5c6cae91d526ac087add64ed14d8444696eb125f788

data/Gemfile

@@ -4,11 +4,17 @@ gemspec
 
 group :test, :development do
   gem 'gem-release'
-  gem 'rspec'
   gem 'pry'
   gem 'rerun'
-  gem 'grape', '~> 0.11.0'
-  gem 'rack-test'
   gem 'yard'
   gem 'webmock'
 end
+
+group :test do
+  gem 'rspec'
+  gem 'rack-test'
+  gem 'codeclimate-test-reporter'
+  gem 'grape', '~> 0.11.0'
+  gem 'grape-entity', '~> 0.4.5'
+end
+

data/README.md

@@ -1,5 +1,9 @@
 # Swaggable
 
+[![Gem Version](https://badge.fury.io/rb/swaggable.svg)](http://badge.fury.io/rb/swaggable)
+[![Build Status](https://travis-ci.org/workshare/swaggable.svg)](https://travis-ci.org/workshare/swaggable)
+[![Code Climate](https://codeclimate.com/github/workshare/swaggable/badges/gpa.svg)](https://codeclimate.com/github/workshare/swaggable)
+
 Flexible swagger documentation generation tool.
 Allows building a Rack application that 
 serves [Swagger 2](http://swagger.io/) documentation 
@@ -16,6 +20,11 @@ api_def = Swaggable::ApiDefinition.from_grape_api(UsersApi)
 rack_app = Swaggable::RackApp.new(api_definition: api_def)
 ```
 
+Mount your rack app as `swagger.json` and you can point Swagger UI to it.
+
+
+## Working with Grape
+
 You can import several Grape APIs:
 
 ```ruby
@@ -34,18 +43,70 @@ api_def.endpoints['GET /users/{id}'].parameters['filter'].description = 'Allows
 api_def.endpoints['GET /users/{id}'].responses[403].description = 'Forbidden'
 ```
 
+It supports status codes and entities. A more complex Grape example here:
+
+```ruby
+class TeamCreateEntity < Grape::Entity
+  def self.name
+    'create team payload'
+  end
+
+  expose :name, documentation: {
+    type: 'String',
+    desc: 'Name for the Team',
+    required: true,
+  }
+end
+
+class TeamsApi < Grape::API
+  format :json
+  content_type :json, 'application/json'
+  version 'v1.0', using: :path, vendor: :workshare
+  prefix "api"
+
+  route_param :account_uuid do
+    resource :teams do
+      desc "Creates a new team for such account"
+
+      params do
+        requires :account_uuid, type: String, desc: 'UUID of the account to be associated with the new team'
+      end
+
+      codes = default_codes + [
+        [201, 'Created'],
+        [422, 'Validations failed'],
+        [404, 'Account not found']
+      ]
+
+      post(http_codes: codes, entity: TeamCreateEntity) do
+        ## Some action here...
+      end
+    end
+  end
+end
+
+api_def = Swaggable::ApiDefinition.from_grape_api(TeamsApi)
+rack_app = Swaggable::RackApp.new(api_definition: api_def)
+```
+
+
+## Validating the resultant Swagger JSON
+
 Validate the results against the corresponding schema in your tests:
 
 ```ruby
 it "validates" do
-  expect(rack_app.validate!).to be true
+  expect(rack_app.validate).to eq []
 end
 ```
 
+
+## Working directly with the DSL
+
 Define the API without Grape:
 
 ```ruby
-api = Swaggable::ApiDefinition.new do
+Swaggable::ApiDefinition.new do
   version '1.0'
   title 'My API'
   description 'A test API'
@@ -53,9 +114,9 @@ api = Swaggable::ApiDefinition.new do
 
   endpoints.add_new do
     path '/users/{id}'
-    verb :get
-    description 'Shows an user'
-    summary 'Returns the JSON representation of such user'
+    verb :put
+    description 'Updates an user'
+    summary 'Updates attributes of such user'
 
     tags.add_new do
       name 'Users'
@@ -70,6 +131,24 @@ api = Swaggable::ApiDefinition.new do
       type :boolean # [:string, :number, :integer, :boolean, :array, :file, nil]
     end
 
+    parameters.add_new do
+      name 'user'
+      description 'The new attributes for the user'
+      location :body
+      required true
+
+      schema do
+        name :user
+
+        attributes do
+          add_new do
+            name :first_name
+            type :string
+          end
+        end
+      end
+    end
+
     responses.add_new do
       status 200
       description 'Success'
@@ -88,21 +167,17 @@ end
 
 ## TODO
 
-* Support response specs.
 * Document classes.
 * Include Redirector.
-* DSL.
-* Swagger validation.
 * Request & response validations.
-* Entities & schemas.
-
+* Response body schemas.
 
 ## Contributing
 
 Do not forget to run the tests with:
 
 ```bash
-rake
+bundle exec rake
 ```
 
 

data/lib/swaggable.rb

@@ -8,7 +8,12 @@ module Swaggable
   autoload :ResponseDefinition, 'swaggable/response_definition'
   autoload :RackApp, 'swaggable/rack_app'
   autoload :GrapeAdapter, 'swaggable/grape_adapter'
+  autoload :GrapeEntityTranslator, 'swaggable/grape_entity_translator'
   autoload :Swagger2Serializer, 'swaggable/swagger_2_serializer'
   autoload :Swagger2Validator, 'swaggable/swagger_2_validator'
   autoload :EndpointIndex, 'swaggable/endpoint_index'
+  autoload :DefinitionBase, 'swaggable/definition_base'
+  autoload :EnumerableAttributes, 'swaggable/enumerable_attributes'
+  autoload :SchemaDefinition, 'swaggable/schema_definition'
+  autoload :AttributeDefinition, 'swaggable/attribute_definition'
 end

data/lib/swaggable/api_definition.rb

@@ -26,6 +26,16 @@ module Swaggable
     def tags
       (endpoints.map(&:tags).reduce(:merge) || []).dup.freeze
     end
+    
+    def used_schemas
+      endpoints.inject([]) do |acc, endpoint|
+        endpoint.parameters.each do |parameter|
+          acc << parameter.schema unless parameter.schema.empty?
+        end
+        
+        acc.uniq
+      end.freeze
+    end
 
     def self.from_grape_api grape
       grape_adapter.import(grape, new)

data/lib/swaggable/attribute_definition.rb

@@ -0,0 +1,72 @@
+module Swaggable
+  class AttributeDefinition
+    include DefinitionBase
+
+    getsetter(
+      :name,
+      :description,
+      :required,
+    )
+
+    attr_enum :type, [
+      :integer,
+      :long,
+      :float,
+      :double,
+      :string,
+      :byte,
+      :boolean,
+      :date,
+      :date_time,
+      :password,
+    ]
+
+    def json_type
+      json_type_hash.fetch(type)
+    end
+
+    def json_format
+      json_format_hash.fetch(type)
+    end
+
+    def required?
+      !!required
+    end
+
+    def optional?
+      !required
+    end
+
+    private
+
+    def json_type_hash
+      {
+        integer: :integer,
+        long: :integer,
+        float: :number,
+        double: :number,
+        string: :string,
+        byte: :string,
+        boolean: :boolean,
+        date: :string,
+        date_time: :string,
+        password: :string,
+      }
+    end
+
+    def json_format_hash
+      {
+        integer: :int32,
+        long: :int64,
+        float: :float,
+        double: :double,
+        string: nil,
+        byte: :byte,
+        boolean: nil,
+        date: :date,
+        date_time: :"date-time",
+        password: :password,
+      }
+    end
+  end
+end

data/lib/swaggable/definition_base.rb

@@ -0,0 +1,15 @@
+require 'forwarding_dsl'
+
+module Swaggable
+  module DefinitionBase
+    def self.included klass
+      klass.send :include, ForwardingDsl::Getsetter
+      klass.send :include, EnumerableAttributes
+    end
+
+    def initialize args = {}, &block
+      args.each {|k, v| self.send("#{k}=", v) }
+      ForwardingDsl.run(self, &block)
+    end
+  end
+end

data/lib/swaggable/endpoint_definition.rb

@@ -3,7 +3,7 @@ require 'mini_object'
 
 module Swaggable
   class EndpointDefinition
-    include ForwardingDsl::Getsetter
+    include DefinitionBase
 
     getsetter(
       :path,
@@ -12,11 +12,6 @@ module Swaggable
       :summary,
     )
 
-    def initialize args = {}, &block
-      args.each {|k, v| self.send("#{k}=", v) }
-      configure(&block) if block_given?
-    end
-
     def tags
       @tags ||= MiniObject::IndexedList.new.tap do |l|
         l.build { TagDefinition.new }

data/lib/swaggable/enumerable_attributes.rb

@@ -0,0 +1,29 @@
+require 'forwarding_dsl'
+
+module Swaggable
+  module EnumerableAttributes
+    def self.included klass
+      klass.send :include, ForwardingDsl::Getsetter
+      klass.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+      def attr_enum name, choices
+        getsetter name
+
+        class_variable_set :"@@valid_#{name}_list", choices
+
+        define_method "#{name}=" do |value|
+          valid_values = self.class.class_variable_get :"@@valid_#{name}_list"
+
+          unless valid_values.include? value
+            raise ArgumentError.new("#{value.inspect} is not one a valid #{name}: #{valid_values.map(&:inspect).join(", ")}")
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+    end
+  end
+end
+

data/lib/swaggable/grape_adapter.rb

@@ -73,6 +73,10 @@ module Swaggable
         api_endpoint.parameters << parameter_from(name, options, grape_endpoint)
       end
 
+      if entity = grape_endpoint.route_entity
+        api_endpoint.parameters << GrapeEntityTranslator.parameter_from(entity)
+      end
+
       (grape_endpoint.route_http_codes || []).each do |status, desc, entity|
         api_endpoint.responses.add_new do |r|
           r.status = status

data/lib/swaggable/grape_entity_translator.rb

@@ -0,0 +1,38 @@
+module Swaggable
+  module GrapeEntityTranslator
+    def self.parameter_from entity
+      ParameterDefinition.new do
+        location :body
+        name entity.name
+        schema.name entity.name
+
+        entity.exposures.each do |name, opts|
+          schema.attributes.add_new do
+            this.name name
+            type type_from_options(opts)
+            description description_from_options(opts)
+            required required_from_options(opts)
+          end
+        end
+      end
+    end
+
+    private
+
+    def self.type_from_options opts
+      documentation = opts[:documentation] || {}
+      type = documentation[:type] || 'string'
+      type.downcase.to_sym
+    end
+
+    def self.description_from_options opts
+      documentation = opts[:documentation] || {}
+      documentation[:desc]
+    end
+
+    def self.required_from_options opts
+      documentation = opts[:documentation] || {}
+      documentation[:required]
+    end
+  end
+end

data/lib/swaggable/parameter_definition.rb

@@ -2,49 +2,34 @@ require 'mini_object'
 
 module Swaggable
   class ParameterDefinition
-    include ForwardingDsl::Getsetter
+    include DefinitionBase
 
     getsetter(
       :name,
       :description,
-      :location,
       :required,
       :type,
+      :schema,
     )
 
-    def initialize args = {}
-      args.each {|k, v| self.send("#{k}=", v) }
-      yield self if block_given?
-    end
+    attr_enum :location, [:path, :query, :header, :body, :form, nil]
+    attr_enum :type, [:string, :number, :integer, :boolean, :array, :file, nil]
 
     def required?
       !!required
     end
 
-    def location= location
-      unless valid_locations.include? location
-        raise ArgumentError.new("#{location} is not one of the valid locations: #{valid_locations.join(", ")}")
-      end
-
-      @location = location
-    end
-
-    def type= type
-      unless valid_types.include? type
-        raise ArgumentError.new("#{type} is not one of the valid types: #{valid_types.join(", ")}")
-      end
-
-      @type = type
+    def schema &block
+      ForwardingDsl.run(
+        @schema ||= build_schema,
+        &block
+      )
     end
 
     private
 
-    def valid_locations
-      [:path, :query, :header, :body, :form, nil]
-    end
-
-    def valid_types
-      [:string, :number, :integer, :boolean, :array, :file, nil]
+    def build_schema
+      SchemaDefinition.new
     end
   end
 end