swaggable 0.4.0

data/spec/swaggable/integration_spec.rb

@@ -0,0 +1,100 @@
+require_relative '../spec_helper'
+require 'rack/test'
+require 'grape'
+
+RSpec.describe 'Integration' do
+  context 'RackApp' do
+    include Rack::Test::Methods
+
+    def app
+      subject
+    end
+
+    subject { rack_app }
+    let(:rack_app) { Swaggable::RackApp.new(api_definition: api_def) }
+    let(:api_def) { Swaggable::ApiDefinition.from_grape_api(grape_api) }
+
+    let(:grape_api) do
+      Class.new(Grape::API).tap do |g|
+        g.params do
+          requires :user_uuid
+        end
+
+        g.get '/' do
+          status 200
+          body({some: 'body'})
+        end
+
+      end.tap do |grape|
+        stub_const('MyGrapeApi', grape)
+      end
+    end
+
+    it 'has status 200 OK' do
+      get '/'
+      expect(last_response.status).to eq 200
+      expect(last_response.headers['Content-Type']).to eq 'application/json'
+    end
+
+    it 'validates' do
+      expect(subject.validate!).to be true
+    end
+  end
+
+  context 'dsl' do
+    it 'supports a full description of the API' do
+      api = Swaggable::ApiDefinition.new do
+        version '1.0'
+        title 'My API'
+        description 'A test API'
+        base_path '/api/1.0'
+
+        endpoints.add_new do
+          path '/users/{id}'
+          verb :get
+          description 'Shows an user'
+          summary 'Returns the JSON representation of such user'
+
+          tags.add_new do
+            name 'Users'
+            description 'Users resource'
+          end
+
+          parameters.add_new do
+            name 'include_comments_count'
+            description 'It will return the comments_count attribute when set to true'
+            location :query # [:path, :query, :header, :body, :form, nil]
+            required false
+            type :boolean # [:string, :number, :integer, :boolean, :array, :file, nil]
+          end
+
+          responses.add_new do
+            status 200
+            description 'Success'
+          end
+
+          responses.add_new do
+            status 404
+            description 'User not found'
+          end
+
+          consumes << :json
+          produces << :json
+        end
+      end
+
+      expect(api.version).to eq '1.0'
+      expect(api.endpoints.first).to be api.endpoints['GET /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'
+      expect(api.endpoints.first.parameters.first).to be api.endpoints.first.parameters['include_comments_count']
+      expect(api.endpoints.first.parameters.first.name).to eq 'include_comments_count'
+      expect(api.endpoints.first.responses.first).to be api.endpoints.first.responses[200]
+      expect(api.endpoints.first.responses.first.description).to eq 'Success'
+      expect(api.endpoints.first.consumes).to eq [:json]
+      expect(api.endpoints.first.produces).to eq [:json]
+    end
+  end
+end
+

data/spec/swaggable/parameter_definition_spec.rb

@@ -0,0 +1,64 @@
+require_relative '../spec_helper'
+
+RSpec.describe 'Swaggable::ParameterDefinition' do
+  let(:subject_class) { Swaggable::ParameterDefinition }
+  let(:subject_instance) { Swaggable::ParameterDefinition.new }
+  subject { subject_instance }
+
+  it 'has a name' do
+    subject.name = 'a name'
+    expect(subject.name).to eq  'a name'
+  end
+
+  it 'has a description' do
+    subject.description = 'a new desc'
+    expect(subject.description).to eq  'a new desc'
+  end
+
+  it 'has a required option' do
+    subject.required = true
+    expect(subject.required?).to be true
+  end
+
+  it 'yields itself on initialize' do
+    yielded = false
+
+    subject_class.new do |s|
+      expect(s).to be_a subject_class
+      yielded = true
+    end
+
+    expect(yielded).to be true
+  end
+
+  describe '#location' do
+    it 'can be set to :body, :header, :path, :query, :form' do
+      [:body, :header, :path, :query, :form, nil].each do |location|
+        subject.location = location
+        expect(subject.location).to eq location
+      end
+    end
+
+    it 'cannot be something other than that' do
+      expect { subject.location = :xyz }.to raise_exception
+    end
+  end
+
+  describe '#type' do
+    it 'can be set to :string, :number, :integer, :boolean, :array, :file' do
+      [:string, :number, :integer, :boolean, :array, :file, nil].each do |type|
+        subject.type = type
+        expect(subject.type).to eq type
+      end
+    end
+
+    it 'cannot be something other than that' do
+      expect { subject.type = :xyz }.to raise_exception
+    end
+  end
+
+  it 'accepts attributes on initialize' do
+    parameter = subject_class.new location: :path
+    expect(parameter.location).to eq :path
+  end
+end

data/spec/swaggable/rack_app_spec.rb

@@ -0,0 +1,49 @@
+require_relative '../spec_helper'
+require 'rack/test'
+
+RSpec.describe 'Swaggable::RackApp' do
+  include Rack::Test::Methods
+
+  let(:subject_class) { Swaggable::RackApp }
+  let(:subject_instance) { Swaggable::RackApp.new serializer: serializer, api_definition: api_definition }
+  subject { subject_instance }
+  let(:api_definition) { instance_double(Swaggable::ApiDefinition) }
+  let(:serializer) { instance_double(Swaggable::Swagger2Serializer, serialize: {}) }
+
+  def app
+    subject_instance
+  end
+
+  it 'has status 200 OK' do
+    get '/'
+    expect(last_response.status).to eq 200
+  end
+
+  it 'has content_type application/json' do
+    get '/'
+    expect(last_response.headers['Content-Type']).to eq 'application/json'
+  end
+
+  it 'has body the serialized swagger' do
+    allow(serializer).to receive(:serialize).with(api_definition).and_return({some: :json})
+
+    get '/'
+    expect(last_response.body).to eq '{"some":"json"}'
+  end
+
+  it 'uses Swagger2Serializer by default' do
+    subject = subject_class.new
+    expect(subject.serializer).to be_a Swaggable::Swagger2Serializer
+  end
+
+  describe 'validate!' do
+    it 'validates against the serializer' do
+      expect(serializer).
+        to receive(:validate!).
+        with api_definition
+
+      subject.validate!
+    end
+  end
+end
+

data/spec/swaggable/response_definition_spec.rb

@@ -0,0 +1,17 @@
+require_relative '../spec_helper'
+
+RSpec.describe 'Swaggable::ResponseDefinition' do
+  let(:subject_class) { Swaggable::ResponseDefinition }
+  let(:subject_instance) { Swaggable::ResponseDefinition.new }
+  subject { subject_instance }
+
+  it 'has a status' do
+    subject.status = 418
+    expect(subject.status).to eq 418
+  end
+
+  it 'has a description' do
+    subject.description = "I'm a teapot"
+    expect(subject.description).to eq "I'm a teapot"
+  end
+end

data/spec/swaggable/swagger_2_serializer_spec.rb

@@ -0,0 +1,208 @@
+require_relative '../spec_helper'
+
+RSpec.describe 'Swaggable::Swagger2Serializer' do
+  let(:subject_class) { Swaggable::Swagger2Serializer }
+  let(:subject_instance) { Swaggable::Swagger2Serializer.new }
+  subject { subject_instance }
+
+  let(:api) { Swaggable::ApiDefinition.new }
+
+  describe '#serialize' do
+    def output
+      subject.serialize(api)
+    end
+
+    it 'has swagger version 2.0' do
+      expect(output[:swagger]).to eq '2.0'
+    end
+
+    it 'has basePath' do
+      api.base_path = '/a/path'
+      expect(output[:basePath]).to eq '/a/path'
+    end
+
+    it 'has title' do
+      api.title = 'A Title'
+      expect(output[:info][:title]).to eq 'A Title'
+    end
+
+    it 'has title empty string if nil' do
+      api.title = nil
+      expect(output[:info][:title]).to eq ''
+    end
+
+    it 'has description' do
+      api.description = 'A Desc'
+      expect(output[:info][:description]).to eq 'A Desc'
+    end
+
+    it 'has no description if nil' do
+      api.description = nil
+      expect(output[:info].has_key?(:description)).to be false
+    end
+
+    it 'has version' do
+      api.version = 'v1.0'
+      expect(output[:info][:version]).to eq 'v1.0'
+    end
+
+    it 'has version "0.0.0" if nil' do
+      api.version = nil
+      expect(output[:info][:version]).to eq "0.0.0"
+    end
+
+    describe '#tags' do
+      def serialized_tag
+        output[:tags].first
+      end
+
+      let(:api) { Swaggable::ApiDefinition.new {|a| a.endpoints << endpoint } }
+      let(:endpoint) { Swaggable::EndpointDefinition.new {|e| e.tags << tag } }
+      let(:tag) { Swaggable::TagDefinition.new name: 'A Tag', description: 'A tag description' } 
+
+      it 'has a name' do
+        expect(serialized_tag[:name]).to eq tag.name
+      end
+
+      it 'has a description' do
+        expect(serialized_tag[:description]).to eq tag.description
+      end
+
+      it 'has no description if nil' do
+        tag.description = nil
+        expect(serialized_tag.has_key?(:description)).to be false
+      end
+    end
+
+    describe '#endpoints' do
+      let(:api) { Swaggable::ApiDefinition.new {|a| a.endpoints << endpoint } }
+      let(:endpoint) { Swaggable::EndpointDefinition.new path: path, verb: verb }
+      let(:path) { '/a/path' }
+      let(:verb) { 'POST' }
+
+      it 'uses the path as key' do
+        expect(output[:paths][path]).not_to be_nil
+      end
+
+      it 'uses the verb as key' do
+        expect(output[:paths][path][verb]).not_to be_nil
+      end
+
+      def serialized_endpoint
+        output[:paths][path][verb]
+      end
+
+      it 'has description' do
+        endpoint.description = 'A desc.'
+        expect(serialized_endpoint[:description]).to eq 'A desc.'
+      end
+
+      it 'has no description if nil' do
+        endpoint.description = nil
+        expect(serialized_endpoint.has_key?(:description)).to be false
+      end
+
+      it 'has summary' do
+        endpoint.summary = 'A summary.'
+        expect(serialized_endpoint[:summary]).to eq 'A summary.'
+      end
+
+      it 'has no summary if summary is nil' do
+        endpoint.summary = nil
+        expect(serialized_endpoint.has_key?(:summary)).to be false
+      end
+
+      it 'has tags' do
+        endpoint.tags << Swaggable::TagDefinition.new(name: 'Tag 1')
+        endpoint.tags << Swaggable::TagDefinition.new(name: 'Tag 2')
+        expect(serialized_endpoint[:tags]).to eq ['Tag 1', 'Tag 2']
+      end
+
+      it 'has consumes' do
+        endpoint.consumes << 'application/whatever'
+        expect(serialized_endpoint[:consumes]).to eq ['application/whatever']
+      end
+
+      it 'has produces' do
+        endpoint.produces << 'application/whatever'
+        expect(serialized_endpoint[:produces]).to eq ['application/whatever']
+      end
+
+      it 'works with two endpoints with the same path' do
+        api.endpoints << Swaggable::EndpointDefinition.new(path: path, verb: 'get')
+
+        expect(output[:paths][path][verb]).not_to be_nil
+        expect(output[:paths][path]['get']).not_to be_nil
+      end
+
+      describe 'responses' do
+        it 'defaults to 200  Success' do
+          expect(serialized_endpoint[:responses]).to eq({200 => {description: "Success"}})
+        end
+
+        it 'is taken from the responses' do
+          endpoint.responses.add_new do
+            status 418
+            description 'Teapot'
+          end
+
+          expect(serialized_endpoint[:responses]).to eq({418 => {description: "Teapot"}})
+        end
+      end
+
+      describe 'parameters' do
+        before(:each) { endpoint.parameters << parameter }
+        let(:parameter) { Swaggable::ParameterDefinition.new location: :query }
+
+        def serialized_parameter
+          serialized_endpoint[:parameters].first
+        end
+
+        it 'has "in"' do
+          expect(serialized_parameter[:in]).to eq 'query'
+        end
+
+        it 'has name' do
+          parameter.name = 'my_param'
+          expect(serialized_parameter[:name]).to eq 'my_param'
+        end
+
+        it 'has description' do
+          parameter.description = 'A param'
+          expect(serialized_parameter[:description]).to eq 'A param'
+        end
+
+        it 'has no description if nil' do
+          parameter.description = nil
+          expect(serialized_parameter.has_key?(:description)).to be false
+        end
+
+        it 'has required' do
+          parameter.required = nil
+          expect(serialized_parameter[:required]).to eq false
+        end
+
+        it 'has type if present' do
+          parameter.type = :string
+          expect(serialized_parameter[:type]).to eq :string
+        end
+
+        it 'has type string if nil' do
+          parameter.type = nil
+          expect(serialized_parameter[:type]).to eq 'string'
+        end
+      end
+    end
+  end
+
+  describe '#validate!' do
+    it 'validates against Swagger2Validator' do
+      expect(Swaggable::Swagger2Validator).
+        to receive(:validate!).
+        with(subject.serialize api).
+        and_return(true)
+
+      subject.validate! api
+    end
+  end
+end

data/spec/swaggable/swagger_2_validator_spec.rb

@@ -0,0 +1,26 @@
+require_relative '../spec_helper'
+require 'json'
+require 'json-schema'
+
+RSpec.describe 'Swaggable::Swagger2Validator' do
+  describe '.validate!' do
+    subject { Swaggable::Swagger2Validator }
+
+    let(:valid_swagger) { JSON.parse File.read('spec/assets/valid-swagger-2.0.json') }
+    let(:invalid_swagger) { valid_swagger.merge("info" => nil) }
+
+    it 'returns true for a valid schema' do
+      expect(subject.validate! valid_swagger).to be true
+    end
+
+    it 'raises exception true for an invalid schema' do
+      expect{ subject.validate! invalid_swagger }.
+        to raise_error(JSON::Schema::ValidationError)#(Swaggable::Swagger2Validator::ValidationError)
+    end
+
+    it 'has a meaningful exception message' do
+      exception = subject.validate!(invalid_swagger) rescue $!
+      expect(exception.message).to match(/info/)
+    end
+  end
+end