swaggable 0.4.0 → 0.5.1

data/lib/swaggable/rack_app.rb

@@ -26,5 +26,9 @@ module  Swaggable
     def validate!
       serializer.validate! api_definition
     end
+
+    def validate
+      serializer.validate api_definition
+    end
   end
 end

data/lib/swaggable/response_definition.rb

@@ -2,15 +2,10 @@ require 'forwarding_dsl'
 
 module Swaggable
   class ResponseDefinition
-    include ForwardingDsl::Getsetter
+    include DefinitionBase
 
     getsetter :status
     getsetter :description
-
-    def initialize args = {}
-      args.each {|k, v| self.send("#{k}=", v) }
-      yield self if block_given?
-    end
   end
 end
 

data/lib/swaggable/schema_definition.rb

@@ -0,0 +1,36 @@
+module Swaggable
+  class SchemaDefinition
+    include DefinitionBase
+
+    getsetter :name
+
+    def attributes &block
+      ForwardingDsl.run(
+        @attributes ||= build_attributes,
+        &block
+      )
+    end
+
+    def empty?
+      attributes.empty?
+    end
+
+    def == other
+      self.name == other.name if other.respond_to?(:name)
+    end
+    alias eql? ==
+
+    def hash
+      name.hash
+    end
+
+    private
+
+    def build_attributes
+      MiniObject::IndexedList.new.tap do |l|
+        l.build { AttributeDefinition.new }
+        l.key {|e| e.name }
+      end
+    end
+  end
+end

data/lib/swaggable/swagger_2_serializer.rb

@@ -18,6 +18,7 @@ module Swaggable
         info: serialize_info(api),
         tags: api.tags.map{|t| serialize_tag t },
         paths: serialize_endpoints(api.endpoints),
+        definitions: serialize_definitions(api),
       }
     end
 
@@ -69,11 +70,40 @@ module Swaggable
         required: parameter.required?,
       }
 
-      p[:type] = parameter.type || 'string'
+      p[:type] = parameter.type || 'string' unless parameter.location == :body
       p[:description] = parameter.description if parameter.description
+
+      unless parameter.schema.empty?
+        p[:schema] = {:"$ref" => "#/definitions/#{parameter.schema.name}"}
+      end
+
       p
     end
 
+    def serialize_parameter_schema schema
+      out = {type: 'object'}
+
+      required_attrs = schema.attributes.select(&:required?)
+      out[:required] = required_attrs.map(&:name) if required_attrs.any?
+
+      out[:properties] = schema.attributes.inject({}) do |acc, attribute|
+        acc[attribute.name] = serialize_parameter_attribute attribute
+        acc
+      end
+
+      out
+    end
+
+    def serialize_parameter_attribute attribute
+      {
+        type: attribute.json_type,
+      }.
+      tap do |e|
+        e[:description] = attribute.description if attribute.description
+        e[:format] = attribute.json_format if attribute.json_format
+      end
+    end
+
     def serialize_responses responses
       if responses.any?
         responses.inject({}) do |acc, r|
@@ -85,8 +115,19 @@ module Swaggable
       end
     end
 
+    def serialize_definitions api
+      api.used_schemas.inject({}) do |acc, schema|
+        acc[schema.name] = serialize_parameter_schema schema
+        acc
+      end
+    end
+
     def validate! api
       Swagger2Validator.validate! serialize(api)
     end
+
+    def validate api
+      Swagger2Validator.validate serialize(api)
+    end
   end
 end

data/lib/swaggable/swagger_2_validator.rb

@@ -7,6 +7,11 @@ module Swaggable
       JSON::Validator.validate!(schema, swagger)
     end
 
+    def self.validate swagger
+      preload_draft4
+      JSON::Validator.fully_validate(schema, swagger, :errors_as_objects => true)
+    end
+
     private
 
     def self.schema

data/lib/swaggable/tag_definition.rb

@@ -2,18 +2,13 @@ require 'forwarding_dsl'
 
 module Swaggable
   class TagDefinition
-    include ForwardingDsl::Getsetter
+    include DefinitionBase
 
     getsetter(
       :name,
       :description,
     )
 
-    def initialize args = {}
-      args.each {|k, v| self.send("#{k}=", v) }
-      yield self if block_given?
-    end
-
     def == other
       self.name == other.name if other.respond_to?(:name)
     end

data/lib/swaggable/version.rb

@@ -1,3 +1,3 @@
 module Swaggable
-  VERSION = '0.4.0'
+  VERSION = '0.5.1'
 end

data/spec/spec_helper.rb

@@ -11,6 +11,13 @@ RSpec.configure do |config|
    # config.formatter = :documentation # :documentation, :progress, :html, :textmate
 end
 
+WebMock.disable_net_connect!(:allow => "codeclimate.com")
+
+if !!ENV['CODECLIMATE_REPO_TOKEN']
+  require 'codeclimate-test-reporter'
+  CodeClimate::TestReporter.start
+end
+
 $LOAD_PATH.unshift File.expand_path('lib')
 require 'swaggable'
 

data/spec/swaggable/api_definition_spec.rb

@@ -123,7 +123,55 @@ RSpec.describe 'Swaggable::ApiDefinition' do
     end
 
     it 'is frozen to avoid giving the false impression that it can be modified' do
-      expect{ subject.tags << instance_double(Swaggable::TagDefinition) }.to raise_error
+      expect{ subject.tags << instance_double(Swaggable::TagDefinition) }.to raise_error(RuntimeError)
+    end
+  end
+
+  describe '#used_schemas' do
+    it 'is collected from params' do
+      schema = instance_double(Swaggable::SchemaDefinition, name: 'An schema', empty?: false)
+      endpoint = Swaggable::EndpointDefinition.new verb: :get, path: '/'
+      parameter = Swaggable::ParameterDefinition.new name: 'A param', schema: schema
+      endpoint.parameters << parameter
+      subject.endpoints << endpoint
+      expect(subject.used_schemas.first).to eq schema
+    end
+
+    it 'avoids duplicates' do
+      schema_1 = Swaggable::SchemaDefinition.new name: 'schema_1'
+      schema_1_again = Swaggable::SchemaDefinition.new name: 'schema_1'
+      schema_2 = Swaggable::SchemaDefinition.new name: 'schema_2'
+
+      schema_1.attributes.add_new { name :attr_1 }
+      schema_1_again.attributes.add_new { name :attr_1 }
+      schema_2.attributes.add_new { name :attr_2 }
+
+      parameter_1 = Swaggable::ParameterDefinition.new name: 'A param', schema: schema_1
+      parameter_2 = Swaggable::ParameterDefinition.new name: 'A param', schema: schema_1_again
+      parameter_3 = Swaggable::ParameterDefinition.new name: 'A param', schema: schema_2
+
+      endpoint_a = Swaggable::EndpointDefinition.new verb: :get, path: '/a'
+      endpoint_b = Swaggable::EndpointDefinition.new verb: :get, path: '/b'
+      endpoint_c = Swaggable::EndpointDefinition.new verb: :get, path: '/c'
+
+      endpoint_a.parameters << parameter_1
+      endpoint_b.parameters << parameter_2
+      endpoint_c.parameters << parameter_3
+
+      subject.endpoints << endpoint_a
+      subject.endpoints << endpoint_b
+      subject.endpoints << endpoint_c
+
+      expect(subject.used_schemas.to_a).to eq [schema_1_again, schema_2]
+    end
+
+    it 'is empty array when no tags are present' do
+      subject.endpoints.clear
+      expect(subject.used_schemas).to eq []
+    end
+
+    it 'is frozen to avoid giving the false impression that it can be modified' do
+      expect{ subject.used_schemas << instance_double(Swaggable::SchemaDefinition) }.to raise_error(RuntimeError)
     end
   end
 

data/spec/swaggable/attribute_definition_spec.rb

@@ -0,0 +1,87 @@
+require_relative '../spec_helper'
+
+RSpec.describe 'Swaggable::AttributeDefinition' do
+  subject { subject_instance }
+  let(:subject_instance) { subject_class.new }
+  let(:subject_class) { Swaggable::AttributeDefinition }
+
+  it 'has a name' do
+    subject.name = 'my_attr'
+    expect(subject.name).to eq 'my_attr'
+  end
+
+  it 'has a description' do
+    subject.description = 'my_attr'
+    expect(subject.description).to eq 'my_attr'
+  end
+
+  it 'has string type' do
+    subject.type :string
+    expect(subject.json_type).to be :string
+    expect(subject.json_format).to be nil
+  end
+
+  it 'has integer type' do
+    subject.type :integer
+    expect(subject.json_type).to be :integer
+    expect(subject.json_format).to be :int32
+  end
+
+  it 'has float type' do
+    subject.type :float
+    expect(subject.json_type).to be :number
+    expect(subject.json_format).to be :float
+  end
+
+  it 'has long type' do
+    subject.type :long
+    expect(subject.json_type).to be :integer
+    expect(subject.json_format).to be :int64
+  end
+
+  it 'has double type' do
+    subject.type :double
+    expect(subject.json_type).to be :number
+    expect(subject.json_format).to be :double
+  end
+
+  it 'has byte type' do
+    subject.type :byte
+    expect(subject.json_type).to be :string
+    expect(subject.json_format).to be :byte
+  end
+
+  it 'has boolean type' do
+    subject.type :boolean
+    expect(subject.json_type).to be :boolean
+    expect(subject.json_format).to be nil
+  end
+
+  it 'has date type' do
+    subject.type :date
+    expect(subject.json_type).to be :string
+    expect(subject.json_format).to be :date
+  end
+
+  it 'has date_time type' do
+    subject.type :date_time
+    expect(subject.json_type).to be :string
+    expect(subject.json_format).to be :"date-time"
+  end
+
+  it 'has password type' do
+    subject.type :password
+    expect(subject.json_type).to be :string
+    expect(subject.json_format).to be :password
+  end
+
+  it 'doesn\'t allow random types' do
+    expect{ subject.type :asdfgh }.to raise_error(ArgumentError)
+  end
+
+  it 'can be required or optional' do
+    subject.required true
+    expect(subject).to be_required
+    expect(subject).not_to be_optional
+  end
+end

data/spec/swaggable/grape_adapter_spec.rb

@@ -1,5 +1,6 @@
 require_relative '../spec_helper'
 require 'grape'
+require 'grape-entity'
 
 RSpec.describe 'Swaggable::GrapeAdapter' do
   let(:subject_class) { Swaggable::GrapeAdapter }
@@ -193,6 +194,27 @@ RSpec.describe 'Swaggable::GrapeAdapter' do
           expect(api.endpoints.first.responses.first.description).to eq 'Created'
         end
       end
+
+      describe 'entities' do
+        it 'generates an schema' do
+          user_class = Class.new(Grape::Entity)
+
+          grape.desc 'Create User', entity: user_class
+          grape.post('/')
+
+          parameter_definition = Swaggable::ParameterDefinition.new name: :first_name
+
+          allow(Swaggable::GrapeEntityTranslator).
+            to receive(:parameter_from).
+            with(user_class).
+            and_return(parameter_definition)
+
+          do_import
+
+          parameter = api.endpoints['POST /'].parameters[:first_name]
+          expect(parameter).to be parameter_definition
+        end
+      end
     end
   end
 end

data/spec/swaggable/grape_entity_translator_spec.rb

@@ -0,0 +1,64 @@
+require_relative '../spec_helper'
+require 'grape'
+require 'grape-entity'
+
+RSpec.describe 'Swaggable::GrapeEntityTranslator' do
+  subject { Swaggable::GrapeEntityTranslator }
+
+  describe '.parameter_from' do
+    let(:generated_parameter) { subject.parameter_from entity }
+
+    let(:entity) do
+      Class.new(Grape::Entity) do
+        def self.name
+          'UserEntity'
+        end
+      end
+    end
+
+    it 'returns a parameter' do
+      expect(generated_parameter).to be_a Swaggable::ParameterDefinition
+    end
+
+    it 'is body param' do
+      expect(generated_parameter.location).to be :body
+    end
+
+    it 'gives it a name' do
+      expect(generated_parameter.name).to eq 'UserEntity'
+    end
+
+    it 'gives a name to the schema too' do
+      expect(generated_parameter.schema.name).to eq 'UserEntity'
+    end
+
+    describe 'schema attributes' do
+      let(:generated_attr) { generated_parameter.schema.attributes.first }
+
+      it 'sets the name' do
+        entity.expose :first_name
+        expect(generated_attr.name).to be :first_name
+      end
+
+      it 'sets the type' do
+        entity.expose :first_name, documentation: {type: 'String'}
+        expect(generated_attr.type).to be :string
+      end
+
+      it 'sets the description' do
+        entity.expose :first_name, documentation: {desc: 'First Name'}
+        expect(generated_attr.description).to eq 'First Name'
+      end
+
+      it 'sets the required field' do
+        entity.expose :first_name, documentation: {required: true}
+        expect(generated_attr).to be_required
+      end
+
+      it 'defaults the required field to false' do
+        entity.expose :first_name, documentation: {}
+        expect(generated_attr).not_to be_required
+      end
+    end
+  end
+end

data/spec/swaggable/integration_spec.rb

@@ -42,8 +42,12 @@ RSpec.describe 'Integration' do
   end
 
   context 'dsl' do
-    it 'supports a full description of the API' do
-      api = Swaggable::ApiDefinition.new do
+    let(:rack_app) { Swaggable::RackApp.new(api_definition: api) }
+
+    let(:swagger) { Swaggable::Swagger2Serializer.new.serialize api }
+
+    let :api do
+      Swaggable::ApiDefinition.new do
         version '1.0'
         title 'My API'
         description 'A test API'
@@ -51,9 +55,9 @@ RSpec.describe 'Integration' 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'
@@ -68,6 +72,24 @@ RSpec.describe 'Integration' 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'
@@ -82,9 +104,11 @@ RSpec.describe 'Integration' do
           produces << :json
         end
       end
+    end
 
+    it 'supports a full description of the API' do
       expect(api.version).to eq '1.0'
-      expect(api.endpoints.first).to be api.endpoints['GET /users/{id}']
+      expect(api.endpoints.first).to be api.endpoints['PUT /users/{id}']
       expect(api.endpoints.first.path).to eq '/users/{id}'
       expect(api.endpoints.first.tags.first).to be api.endpoints.first.tags['Users']
       expect(api.endpoints.first.tags.first.name).to eq 'Users'
@@ -95,6 +119,26 @@ RSpec.describe 'Integration' do
       expect(api.endpoints.first.consumes).to eq [:json]
       expect(api.endpoints.first.produces).to eq [:json]
     end
+
+    it 'renders proper swagger JSON' do
+      param_schema = swagger[:paths]["/users/{id}"][:put][:parameters].detect{|p| p[:name] == 'user' }[:schema]
+
+      expected_param_schema = {
+        type: 'object',
+        properties: {
+          first_name: {
+            type: :string,
+          }
+        }
+      }
+
+      expect(param_schema).to eq({:$ref => "#/definitions/user"})
+      expect(swagger[:definitions][:user]).to eq expected_param_schema
+    end
+
+    it 'validates' do
+      expect(rack_app.validate).to be_empty
+    end
   end
 end