grape-swagger 0.11.0 → 0.20.0

data/spec/swagger_v2/api_swagger_v2_spec.rb

@@ -0,0 +1,207 @@
+require 'spec_helper'
+
+describe 'swagger spec v2.0' do
+  include_context "swagger example"
+
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      #  Thing stuff
+      desc 'This gets Things.' do
+        params Entities::Something.documentation
+        http_codes [ { code: 401, message: 'Unauthorized', model: Entities::ApiError } ]
+      end
+      get '/thing' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'This gets Things.' do
+        http_codes [
+          { code: 200, message: 'get Horses', model: Entities::Something },
+          { code: 401, message: 'HorsesOutError', model: Entities::ApiError }
+        ]
+      end
+      get '/thing2' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'This gets Thing.' do
+        http_codes [ { code: 200, message: 'getting a single thing' }, { code: 401, message: 'Unauthorized' } ]
+      end
+      params do
+        requires :id, type: Integer
+      end
+      get '/thing/:id' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'This creates Thing.',
+        success: Entities::Something
+      params do
+        requires :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
+        requires :links, type: Array, documentation: { type: 'link', is_array: true }
+      end
+      post '/thing', http_codes: [ { code: 422, message: 'Unprocessible Entity' } ] do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'This updates Thing.',
+        success: Entities::Something
+      params do
+        requires :id, type: Integer
+        optional :text, type: String, desc: 'Content of something.'
+        optional :links, type: Array, documentation: { type: 'link', is_array: true }
+      end
+      put '/thing/:id' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'This deletes Thing.',
+        entity: Entities::Something
+      params do
+        requires :id, type: Integer
+      end
+      delete '/thing/:id' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+
+      desc 'dummy route.',
+        failure: [{ code: 401, message: 'Unauthorized' }]
+      params do
+        requires :id, type: Integer
+      end
+      delete '/dummy/:id' do
+      end
+
+      namespace :other_thing do
+        desc 'nested route inside namespace',
+          entity: Entities::QueryInput,
+          x: {
+            'amazon-apigateway-auth' => {type: 'none'},
+            'amazon-apigateway-integration' => {type: 'aws', uri: 'foo_bar_uri', httpMethod: 'get'}
+          }
+
+        params do
+          requires :elements, documentation: {
+            type: 'QueryInputElement',
+            desc: 'Set of configuration',
+            param_type: 'body',
+            is_array: true,
+            required: true
+          }
+        end
+        get '/:elements' do
+          present something, with: Entities::QueryInput
+        end
+      end
+
+
+      version 'v3', using: :path
+      add_swagger_documentation api_version: 'v1',
+                                base_path: '/api',
+                                info: {
+                                  title: "The API title to be displayed on the API homepage.",
+                                  description: "A description of the API.",
+                                  contact_name: "Contact name",
+                                  contact_email: "Contact@email.com",
+                                  contact_url: "Contact URL",
+                                  license: "The name of the license.",
+                                  license_url: "www.The-URL-of-the-license.org",
+                                  terms_of_service_url: "www.The-URL-of-the-terms-and-service.com",
+                                }
+    end
+  end
+
+  before do
+    get '/v3/swagger_doc'
+  end
+
+  let(:json) { JSON.parse(last_response.body) }
+
+  describe 'swagger object' do
+    describe 'required keys' do
+      it { expect(json.keys).to include 'swagger' }
+      it { expect(json['swagger']).to eql '2.0'  }
+      it { expect(json.keys).to include 'info' }
+      it { expect(json['info']).to be_a Hash  }
+      it { expect(json.keys).to include 'paths' }
+      it { expect(json['paths']).to be_a Hash  }
+    end
+
+    describe 'info object required keys' do
+      let(:info) { json['info'] }
+
+      it { expect(info.keys).to include 'title' }
+      it { expect(info['title']).to be_a String  }
+      it { expect(info.keys).to include 'version' }
+      it { expect(info['version']).to be_a String  }
+
+      describe 'license object' do
+        let(:license) { json['info']['license'] }
+
+        it { expect(license.keys).to include 'name' }
+        it { expect(license['name']).to be_a String  }
+        it { expect(license.keys).to include 'url' }
+        it { expect(license['url']).to be_a String  }
+      end
+
+      describe 'contact object' do
+        let(:contact) { json['info']['contact'] }
+
+        it { expect(contact.keys).to include 'name' }
+        it { expect(contact['name']).to be_a String  }
+        it { expect(contact.keys).to include 'email' }
+        it { expect(contact['email']).to be_a String  }
+        it { expect(contact.keys).to include 'url' }
+        it { expect(contact['url']).to be_a String  }
+      end
+    end
+
+    describe 'path object' do
+      let(:paths) { json['paths'] }
+
+      it "hides documentation paths per default" do
+        expect(paths.keys).not_to include '/swagger_doc', '/swagger_doc/{name}'
+      end
+
+      specify do
+        paths.each_pair do |path, value|
+          expect(path).to start_with('/')
+          expect(value).to be_a Hash
+          expect(value).not_to be_empty
+
+          value.each do |method, declaration|
+            expect(http_verbs).to include method
+            expect(declaration).to have_key('responses')
+
+            declaration["responses"].each do |status_code, response|
+              expect(status_code).to match(/\d{3}/)
+              expect(response).to have_key('description')
+            end
+          end
+        end
+      end
+    end
+
+    describe 'definitions object' do
+      let(:definitions) { json['definitions'] }
+      specify do
+        definitions.each do |model, properties|
+          expect(model).to match(/\w+/)
+          expect(properties).to have_key('properties')
+        end
+      end
+    end
+  end
+
+  describe "swagger file" do
+    it { expect(json).to eql swagger_json }
+  end
+end

data/spec/swagger_v2/api_swagger_v2_type-format_spec.rb

@@ -0,0 +1,121 @@
+require 'spec_helper'
+
+# mapping of parameter types
+# Grape                         ->  Swagger (OpenApi)
+#                                   (type format)
+# ---------------------------------------------------
+# Integer                       ->  integer int32
+# Numeric                       ->  integer int64
+# Float                         ->  number float
+# BigDecimal                    ->  number double
+# String                        ->  string
+# Symbol                        ->  string
+# Date                          ->  string date
+# DateTime                      ->  string date-time
+# Time                          ->  string date-time
+# 'password'                    ->  string password
+# 'email'                       ->  string email
+# Boolean                       ->  boolean
+# JSON                          ->  json
+# Rack::Multipart::UploadedFile ->  file
+
+describe 'type format settings' do
+  before :all do
+    module TheApi
+      module Entities
+        class TypedDefinition < Grape::Entity
+          expose :prop_integer,   documentation: { type: Integer, desc: 'prop_integer' }
+          expose :prop_long,      documentation: { type: Numeric, desc: 'prop_long' }
+          expose :prop_float,     documentation: { type: Float, desc: 'prop_float' }
+          expose :prop_double,    documentation: { type: BigDecimal, desc: 'prop_double' }
+          expose :prop_string,    documentation: { type: String, desc: 'prop_string' }
+          expose :prop_symbol,    documentation: { type: Symbol, desc: 'prop_symbol' }
+          expose :prop_date,      documentation: { type: Date, desc: 'prop_date' }
+          expose :prop_date_time, documentation: { type: DateTime, desc: 'prop_date_time' }
+          expose :prop_time,      documentation: { type: Time, desc: 'prop_time' }
+          expose :prop_password,  documentation: { type: 'password', desc: 'prop_password' }
+          expose :prop_email,     documentation: { type: 'email', desc: 'prop_email' }
+          expose :prop_boolean,   documentation: { type: Virtus::Attribute::Boolean, desc: 'prop_boolean' }
+          expose :prop_file,      documentation: { type: File, desc: 'prop_file' }
+          expose :prop_json,      documentation: { type: JSON, desc: 'prop_json' }
+        end
+      end
+
+      class TypeFormatApi < Grape::API
+        desc 'full set of request data types',
+          success: TheApi::Entities::TypedDefinition
+
+        params do
+          # grape supported data types
+          requires :param_integer,   type: Integer
+          requires :param_long,      type: Numeric
+          requires :param_float,     type: Float
+          requires :param_double,    type: BigDecimal
+          optional :param_string,    type: String
+          optional :param_symbol,    type: Symbol
+          requires :param_date,      type: Date
+          requires :param_date_time, type: DateTime
+          requires :param_time,      type: Time
+          requires :param_password,  type: 'password'
+          requires :param_email,     type: 'email'
+          optional :param_boolean,   type: Boolean
+          optional :param_file,      type: File
+          optional :param_json,      type: JSON
+        end
+
+        post '/request_types' do
+          { "declared_params" => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::TypeFormatApi
+  end
+
+  subject do
+    get '/swagger_doc/request_types'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject['paths']['/request_types']['post']['parameters']).to eql([
+      {"in"=>"formData", "name"=>"param_integer", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
+      {"in"=>"formData", "name"=>"param_long", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int64"},
+      {"in"=>"formData", "name"=>"param_float", "description"=>nil, "required"=>true, "type"=>"number", "format"=>"float"},
+      {"in"=>"formData", "name"=>"param_double", "description"=>nil, "required"=>true, "type"=>"number", "format"=>"double"},
+      {"in"=>"formData", "name"=>"param_string", "description"=>nil, "required"=>false, "type"=>"string"},
+      {"in"=>"formData", "name"=>"param_symbol", "description"=>nil, "required"=>false, "type"=>"string"},
+      {"in"=>"formData", "name"=>"param_date", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"date"},
+      {"in"=>"formData", "name"=>"param_date_time", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"date-time"},
+      {"in"=>"formData", "name"=>"param_time", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"date-time"},
+      {"in"=>"formData", "name"=>"param_password", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"password"},
+      {"in"=>"formData", "name"=>"param_email", "description"=>nil, "required"=>true, "type"=>"string", "format"=>"email"},
+      {"in"=>"formData", "name"=>"param_boolean", "description"=>nil, "required"=>false, "type"=>"boolean"},
+      {"in"=>"formData", "name"=>"param_file", "description"=>nil, "required"=>false, "type"=>"file"},
+      {"in"=>"formData", "name"=>"param_json", "description"=>nil, "required"=>false, "type"=>"json"}
+    ])
+  end
+
+  specify do
+    expect(subject['definitions']['TypedDefinition']['properties']).to eql({
+      "prop_integer"=>{"type"=>"integer", "format"=>"int32"},
+      "prop_long"=>{"type"=>"integer", "format"=>"int64"},
+      "prop_float"=>{"type"=>"number", "format"=>"float"},
+      "prop_double"=>{"type"=>"number", "format"=>"double"},
+      "prop_string"=>{"type"=>"string"},
+      "prop_symbol"=>{"type"=>"string"},
+      "prop_date"=>{"type"=>"string", "format"=>"date"},
+      "prop_date_time"=>{"type"=>"string", "format"=>"date-time"},
+      "prop_time"=>{"type"=>"string", "format"=>"date-time"},
+      "prop_password"=>{"type"=>"string", "format"=>"password"},
+      "prop_email"=>{"type"=>"string", "format"=>"email"},
+      "prop_boolean"=>{"type"=>"boolean"},
+      "prop_file"=>{"type"=>"file"},
+      "prop_json"=>{"type"=>"json"}
+    })
+  end
+end

data/spec/{boolean_params_spec.rb → swagger_v2/boolean_params_spec.rb}

@@ -19,12 +19,12 @@ describe 'Boolean Params' do
     get '/swagger_doc/splines'
     expect(last_response.status).to eq 200
     body = JSON.parse last_response.body
-    body['apis'].first['operations'].first['parameters']
+    body['paths']['/splines']['post']['parameters']
   end
 
   it 'converts boolean types' do
     expect(subject).to eq [
-      { 'paramType' => 'form', 'name' => 'a_boolean', 'description' => '', 'type' => 'boolean', 'required' => true, 'allowMultiple' => false }
+      {"in"=>"formData", "name"=>"a_boolean", "description"=>nil, "type"=>"boolean", "required"=>true}
     ]
   end
 end

data/spec/{default_api_spec.rb → swagger_v2/default_api_spec.rb}

@@ -1,5 +1,5 @@
 require 'spec_helper'
-require 'grape_version'
+# require 'grape_version'
 
 describe 'Default API' do
   context 'with no additional options' do
@@ -21,32 +21,38 @@ describe 'Default API' do
 
     it 'documents api' do
       expect(subject).to eq(
-        'apiVersion' => '0.1',
-        'swaggerVersion' => '1.2',
-        'info' => {},
-        'produces' => ['application/json'],
-        'apis' => [
-          { 'path' => '/something.{format}', 'description' => 'Operations about somethings' },
-          { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
-        ]
+        {
+          "info"=>{"title"=>"API title", "version"=>"v1"},
+          "swagger"=>"2.0",
+          "produces"=>["application/json"],
+          "host"=>"example.org",
+          "tags" => [{"name"=>"something", "description"=>"Operations about somethings"}],
+          "schemes" => ["https", "http"],
+          "paths"=>{
+            "/something"=>{
+              "get"=>{
+                "description"=>"This gets something.",
+                "produces"=>["application/json"],
+                "tags"=>["something"],
+                "operationId"=>"getSomething",
+                "responses"=>{"200"=>{"description"=>"This gets something."}}}}}}
       )
     end
 
     context 'path inside the apis array' do
       it 'starts with a forward slash' do
-        subject['apis'].each do |api|
-          expect(api['path']).to start_with '/'
+        subject['paths'].each do |path|
+          expect(path.first).to start_with '/'
         end
       end
     end
   end
+
   context 'with additional option block given to desc', if: GrapeVersion.satisfy?('>= 0.12.0') do
     def app
       Class.new(Grape::API) do
         format :json
-        desc 'This gets something.' do
-          detail 'more details about the endpoint'
-        end
+        desc 'This gets something.'
         get '/something' do
           { bla: 'something' }
         end
@@ -60,24 +66,22 @@ describe 'Default API' do
     end
 
     it 'documents endpoint' do
-      expect(subject).to eq(
-        'apiVersion'     => '0.1',
-        'swaggerVersion' => '1.2',
-        'basePath'       => 'http://example.org',
-        'produces'       => ['application/json'],
-        'resourcePath'   => '/something',
-        'apis'           => [{
-          'path' => '/something.{format}',
-          'operations' => [{
-            'notes'      => 'more details about the endpoint',
-            'summary'    => 'This gets something.',
-            'nickname'   => 'GET-something--json-',
-            'method'     => 'GET',
-            'parameters' => [],
-            'type'       => 'void'
-          }]
-        }]
-      )
+      expect(subject).to eq({
+        "info"=>{"title"=>"API title", "version"=>"v1"},
+        "swagger"=>"2.0",
+        "produces"=>["application/json"],
+        "host"=>"example.org",
+        "tags" => [{"name"=>"something", "description"=>"Operations about somethings"}],
+        "schemes" => ["https", "http"],
+        "paths"=>{
+          "/something"=>{
+            "get"=>{
+              "description"=>"This gets something.",
+              "produces"=>["application/json"],
+              "tags"=>["something"],
+              "operationId"=>"getSomething",
+              "responses"=>{"200"=>{"description"=>"This gets something."}}}}}
+      })
     end
   end
 
@@ -91,7 +95,7 @@ describe 'Default API' do
           license: 'Apache 2',
           license_url: 'http://test.com',
           terms_of_service_url: 'http://terms.com',
-          contact: 'support@test.com'
+          contact_email: 'support@test.com'
         }
       end
     end
@@ -110,11 +114,11 @@ describe 'Default API' do
     end
 
     it 'should document the license' do
-      expect(subject['license']).to eql('Apache 2')
+      expect(subject['license']['name']).to eql('Apache 2')
     end
 
     it 'documents the license url' do
-      expect(subject['licenseUrl']).to eql('http://test.com')
+      expect(subject['license']['url']).to eql('http://test.com')
     end
 
     it 'documents the terms of service url' do
@@ -122,7 +126,7 @@ describe 'Default API' do
     end
 
     it 'documents the contact email' do
-      expect(subject['contact']).to eql('support@test.com')
+      expect(subject['contact']['email']).to eql('support@test.com')
     end
   end
 end