grape-swagger 0.11.0 → 0.20.0

data/spec/swagger_v2/api_swagger_v2_format-content_type_spec.rb

@@ -0,0 +1,124 @@
+require 'spec_helper'
+
+describe 'format, content_type' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class ProducesApi < Grape::API
+        format :json
+
+        desc 'This uses json (default) for produces',
+          failure: [{code: 400, model: Entities::ApiError}],
+          entity: Entities::UseResponse
+        get '/use_default' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This uses formats for produces',
+          failure: [{code: 400, model: Entities::ApiError}],
+          formats: [:xml, :binary, "application/vdns"],
+          entity: Entities::UseResponse
+        get '/use_formats' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This uses content_types for produces',
+          failure: [{code: 400, model: Entities::ApiError}],
+          content_types: [:xml, :binary, "application/vdns"],
+          entity: Entities::UseResponse
+        get '/use_content_types' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This uses produces for produces',
+          failure: [{code: 400, model: Entities::ApiError}],
+          produces: [:xml, :binary, "application/vdns"],
+          entity: Entities::UseResponse
+        get '/use_produces' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This uses produces for produces',
+          failure: [{code: 400, model: Entities::ApiError}],
+          consumes: ["application/www_url_encoded"],
+          entity: Entities::UseResponse
+        post '/use_consumes' do
+          { "declared_params" => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ProducesApi
+  end
+
+  let(:produced) {[
+    'application/xml',
+    'application/octet-stream',
+    'application/vdns'
+  ]}
+
+  describe "formats" do
+    subject do
+      get '/swagger_doc/use_default'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_default']['get']).to include('produces')
+      expect(subject['paths']['/use_default']['get']['produces']).to eql(['application/json'])
+    end
+  end
+
+  describe "formats" do
+    subject do
+      get '/swagger_doc/use_formats'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_formats']['get']).to include('produces')
+      expect(subject['paths']['/use_formats']['get']['produces']).to eql(produced)
+    end
+  end
+
+  describe "content types" do
+    subject do
+      get '/swagger_doc/use_content_types'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_content_types']['get']).to include('produces')
+      expect(subject['paths']['/use_content_types']['get']['produces']).to eql(produced)
+      end
+  end
+
+  describe "produces" do
+    subject do
+      get '/swagger_doc/use_produces'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_produces']['get']).to include('produces')
+      expect(subject['paths']['/use_produces']['get']['produces']).to eql(produced)
+    end
+  end
+
+  describe "consumes" do
+    subject do
+      get '/swagger_doc/use_consumes'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_consumes']['post']).to include('consumes')
+      expect(subject['paths']['/use_consumes']['post']['consumes']).to eql ["application/www_url_encoded"]
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe 'global configuration stuff' do
+
+  before :all do
+    module TheApi
+      class ConfigurationApi < Grape::API
+        format :json
+        version 'v3', using: :path
+
+        desc 'This returns something',
+          failure: [{code: 400, message: 'NotFound'}]
+        params do
+          requires :foo, type: Integer
+        end
+        get :configuration do
+          { "declared_params" => declared(params) }
+        end
+
+        add_swagger_documentation format: :json,
+                                  api_version: '23',
+                                  schemes: 'https',
+                                  host: -> { 'another.host.com' },
+                                  base_path: -> { 'somewhere/over/the/rainbow' },
+                                  mount_path: 'documentation',
+                                  add_base_path: true,
+                                  add_version: true
+
+      end
+    end
+  end
+
+  def app
+    TheApi::ConfigurationApi
+  end
+
+  describe "shows documentation paths" do
+    subject do
+      get '/v3/documentation'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['host']).to eql 'another.host.com'
+      expect(subject['basePath']).to eql 'somewhere/over/the/rainbow'
+      expect(subject['paths'].keys.first).to eql '/somewhere/over/the/rainbow/v3/configuration'
+      expect(subject['schemes']).to eql ['https']
+    end
+  end
+
+end

data/spec/swagger_v2/api_swagger_v2_headers_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+
+describe 'headers' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class HeadersApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+          failure: [{code: 400, model: Entities::ApiError}],
+          headers:  {
+            "X-Rate-Limit-Limit" => {
+              "description" => "The number of allowed requests in the current period",
+              "type" => "integer"
+          }},
+
+          entity: Entities::UseResponse
+        get '/use_headers' do
+          { "declared_params" => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::HeadersApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject['paths']['/use_headers']['get']).to include('headers')
+    expect(subject['paths']['/use_headers']['get']['headers']).to eql({
+      "X-Rate-Limit-Limit"=>{"description"=>"The number of allowed requests in the current period", "type"=>"integer"}
+    })
+  end
+end

data/spec/swagger_v2/api_swagger_v2_hide_documentation_path_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe 'hide documentation path' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class HideDocumentationApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+          params: Entities::UseResponse.documentation,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        params do
+          requires :foo, type: Integer
+        end
+        get '/params_response' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This returns something',
+          entity: Entities::UseResponse,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        get '/entity_response' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This returns something',
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        get '/present_response' do
+          foo = OpenStruct.new id: 1, name: 'bar'
+          something = OpenStruct.new description: 'something', item: foo
+          present :somethings, something, with: Entities::UseResponse
+        end
+
+        add_swagger_documentation hide_documentation_path: false
+      end
+    end
+  end
+
+  def app
+    TheApi::HideDocumentationApi
+  end
+
+  describe "shows documentation paths" do
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths'].keys).to include '/swagger_doc', '/swagger_doc/{name}'
+    end
+  end
+
+end

data/spec/swagger_v2/api_swagger_v2_mounted_spec.rb

@@ -0,0 +1,146 @@
+require 'spec_helper'
+
+describe 'swagger spec v2.0' do
+  describe 'mounted APIs' 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 hide_format: true,
+                                  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
+
+    mounted_paths.each do |expected_path|
+      describe "documents only #{expected_path} paths" do
+        let(:mount_path) { "/v3/swagger_doc#{expected_path}" }
+        subject do
+          get mount_path
+          JSON.parse(last_response.body)['paths']
+        end
+
+        specify do
+          unexpected_paths = mounted_paths - [expected_path]
+          subject.keys.each do |path|
+            unexpected_paths.each do |unexpected_path|
+              expect(path).not_to start_with unexpected_path
+            end
+            expect(path).to start_with(expected_path).or include(expected_path)
+            expect(subject[path]).to eql swagger_json['paths'][path]
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/spec/swagger_v2/api_swagger_v2_param_type_body_nested_spec.rb

@@ -0,0 +1,197 @@
+require 'spec_helper'
+
+describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `header`' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class NestedBodyParamTypeApi < Grape::API
+        namespace :simple_nested_params do
+          desc 'post in body with nested parameters',
+            detail: 'more details description',
+            success: TheApi::Entities::UseNestedWithAddress
+          params do
+            requires :name, type: String, documentation: { desc: 'name', in: 'body' }
+            optional :address, type: Hash do
+              requires :street, type: String, documentation: { desc: 'street', in: 'body' }
+              requires :postcode, type: String, documentation: { desc: 'postcode', in: 'body' }
+              requires :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+          end
+
+          post '/in_body' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'put in body with nested parameters',
+            detail: 'more details description',
+            success: TheApi::Entities::UseNestedWithAddress
+          params do
+            requires :id, type: Integer
+            optional :name, type: String, documentation: { desc: 'name', in: 'body' }
+            optional :address, type: Hash do
+              optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+              optional :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+              optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+          end
+
+          put '/in_body/:id' do
+            { "declared_params" => declared(params) }
+          end
+        end
+
+        namespace :multiple_nested_params do
+          desc 'put in body with multiple nested parameters',
+            success: TheApi::Entities::UseNestedWithAddress
+          params do
+            requires :id, type: Integer
+            optional :name, type: String, documentation: { desc: 'name', in: 'body' }
+            optional :address, type: Hash do
+              optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+              requires :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+              optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+            optional :delivery_address, type: Hash do
+              optional :street, type: String, documentation: { desc: 'street', in: 'body' }
+              optional :postcode, type: String, documentation: { desc: 'postcode', in: 'formData' }
+              optional :city, type: String, documentation: { desc: 'city', in: 'body' }
+              optional :country, type: String, documentation: { desc: 'country', in: 'body' }
+            end
+          end
+
+          put '/in_body/:id' do
+            { "declared_params" => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::NestedBodyParamTypeApi
+  end
+
+  describe 'nested body parameters given' do
+    subject do
+      get '/swagger_doc/simple_nested_params'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/simple_nested_params/in_body']['post']['parameters']).to eql([{
+        "name"=>"UseNestedWithAddress",
+        "in"=>"body",
+        "required"=>true,
+        "schema"=>{"$ref"=>"#/definitions/postRequestUseNestedWithAddress"}
+      }])
+    end
+
+    specify do
+      expect(subject['definitions']['postRequestUseNestedWithAddress']).to eql({
+        "description"=>"post in body with nested parameters\n more details description",
+        "type"=>"object",
+        "properties"=>{
+          "address"=>{"$ref"=>"#/definitions/postRequestUseNestedWithAddressAddress"},
+          "name"=>{"type"=>"string", "description"=>"name"}
+        },
+        "required"=>["name"]
+      })
+      expect(subject['definitions']['postRequestUseNestedWithAddressAddress']).to eql({
+        "description"=>"postRequestUseNestedWithAddress - address",
+        "type"=>"object",
+        "properties"=>{
+          "street"=>{"type"=>"string", "description"=>"street"},
+          "postcode"=>{"type"=>"string", "description"=>"postcode"},
+          "city"=>{"type"=>"string", "description"=>"city"},
+          "country"=>{"type"=>"string", "description"=>"country"}
+        },
+        "required"=>["street", "postcode", "city"]
+      })
+    end
+
+    specify do
+      expect(subject['paths']['/simple_nested_params/in_body/{id}']['put']['parameters']).to eql([
+        {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
+        {
+          "name"=>"UseNestedWithAddress",
+          "in"=>"body",
+          "required"=>true,
+          "schema"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddress"}
+        }
+      ])
+    end
+
+    specify do
+      expect(subject['definitions']['putRequestUseNestedWithAddress']).to eql({
+        "description" => "put in body with nested parameters\n more details description",
+        "type"=>"object",
+        "properties"=>{
+          "address"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddressAddress"},
+          "id"=>{"type"=>"integer", "format"=>"int32", "readOnly"=>true},
+          "name"=>{"type"=>"string", "description"=>"name"}
+        }
+      })
+      expect(subject['definitions']['putRequestUseNestedWithAddressAddress']).to eql({
+        "description"=>"putRequestUseNestedWithAddress - address",
+        "type"=>"object",
+        "properties"=>{
+          "street"=>{"type"=>"string", "description"=>"street"},
+          "postcode"=>{"type"=>"string", "description"=>"postcode"},
+          "city"=>{"type"=>"string", "description"=>"city"},
+          "country"=>{"type"=>"string", "description"=>"country"}}
+      })
+    end
+  end
+
+  describe 'multiple nested body parameters given' do
+    subject do
+      get '/swagger_doc/multiple_nested_params'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/multiple_nested_params/in_body/{id}']['put']['parameters']).to eql([
+        {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
+        {"name"=>"UseNestedWithAddress", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddress"}}
+      ])
+    end
+
+    specify do
+      expect(subject['definitions']['putRequestUseNestedWithAddress']).to eql({
+        "description" => "put in body with multiple nested parameters",
+        "type"=>"object",
+        "properties"=>{
+          "address"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddressAddress"},
+          "delivery_address"=>{"$ref"=>"#/definitions/putRequestUseNestedWithAddressDeliveryAddress"},
+          "id"=>{"type"=>"integer", "format"=>"int32", "readOnly"=>true},
+          "name"=>{"type"=>"string", "description"=>"name"}
+      }})
+      expect(subject['definitions']['putRequestUseNestedWithAddressAddress']).to eql({
+        "description" => "putRequestUseNestedWithAddress - address",
+        "type"=>"object",
+        "properties"=>{
+          "street"=>{"type"=>"string", "description"=>"street"},
+          "postcode"=>{"type"=>"string", "description"=>"postcode"},
+          "city"=>{"type"=>"string", "description"=>"city"},
+          "country"=>{"type"=>"string", "description"=>"country"}
+        },
+        "required"=>["postcode"]
+      })
+      expect(subject['definitions']['putRequestUseNestedWithAddressDeliveryAddress']).to eql({
+        "description" => "putRequestUseNestedWithAddress - delivery_address",
+        "type"=>"object",
+        "properties"=>{
+          "street"=>{"type"=>"string", "description"=>"street"},
+          "postcode"=>{"type"=>"string", "description"=>"postcode"},
+          "city"=>{"type"=>"string", "description"=>"city"},
+          "country"=>{"type"=>"string", "description"=>"country"}
+      }})
+    end
+  end
+end