grape-swagger 0.11.0 → 0.20.0

data/spec/swagger_v2/api_swagger_v2_param_type_body_spec.rb

@@ -0,0 +1,151 @@
+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 BodyParamTypeApi < Grape::API
+        namespace :wo_entities do
+          desc 'post in body /wo entity'
+          params do
+            requires :in_body_1, type: Integer, documentation: { desc: 'in_body_1', param_type: 'body' }
+            optional :in_body_2, type: String, documentation: { desc: 'in_body_2', param_type: 'body' }
+            optional :in_body_3, type: String, documentation: { desc: 'in_body_3', param_type: 'body' }
+          end
+
+          post '/in_body' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'put in body /wo entity'
+          params do
+            requires :key, type: Integer
+            optional :in_body_1, type: Integer, documentation: { desc: 'in_body_1', param_type: 'body' }
+            optional :in_body_2, type: String, documentation: { desc: 'in_body_2', param_type: 'body' }
+            optional :in_body_3, type: String, documentation: { desc: 'in_body_3', param_type: 'body' }
+          end
+
+          put '/in_body/:key' do
+            { "declared_params" => declared(params) }
+          end
+        end
+
+        namespace :with_entities do
+          desc 'post in body with entity',
+            success: TheApi::Entities::ResponseItem
+          params do
+            requires :name, type: String, documentation: { desc: 'name', param_type: 'body' }
+          end
+
+          post '/in_body' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'put in body with entity',
+            success: TheApi::Entities::ResponseItem
+          params do
+            requires :id, type: Integer
+            optional :name, type: String, documentation: { desc: 'name', param_type: 'body' }
+          end
+
+          put '/in_body/:id' do
+            { "declared_params" => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::BodyParamTypeApi
+  end
+
+  describe 'no entity given' do
+    subject do
+      get '/swagger_doc/wo_entities'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/wo_entities/in_body']['post']['parameters']).to eql([
+        {"name"=>"InBody", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/postRequestInBody"}}
+      ])
+    end
+
+    specify do
+      expect(subject['definitions']['postRequestInBody']).to eql({
+        "description" => "post in body /wo entity",
+        "type"=>"object",
+        "properties"=>{
+          "in_body_1"=>{"type"=>"integer", "format"=>"int32", "description"=>"in_body_1"},
+          "in_body_2"=>{"type"=>"string", "description"=>"in_body_2"},
+          "in_body_3"=>{"type"=>"string", "description"=>"in_body_3"}
+        },
+        "required"=>["in_body_1"]
+      })
+    end
+
+    specify do
+      expect(subject['paths']['/wo_entities/in_body/{key}']['put']['parameters']).to eql([
+        {"in"=>"path", "name"=>"key", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
+        {"name"=>"InBody", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestInBody"}}
+      ])
+    end
+
+    specify do
+      expect(subject['definitions']['putRequestInBody']).to eql({
+        "description" => "put in body /wo entity",
+        "type"=>"object",
+        "properties"=>{
+          "key"=>{"type"=>"integer", "format"=>"int32", "readOnly"=>true},
+          "in_body_1"=>{"type"=>"integer", "format"=>"int32", "description"=>"in_body_1"},
+          "in_body_2"=>{"type"=>"string", "description"=>"in_body_2"},
+          "in_body_3"=>{"type"=>"string", "description"=>"in_body_3"}
+        }
+      })
+    end
+  end
+
+  describe 'entity given' do
+    subject do
+      get '/swagger_doc/with_entities'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/with_entities/in_body']['post']['parameters']).to eql([
+        {"name"=>"ResponseItem", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/postRequestResponseItem"}}
+      ])
+    end
+
+    specify do
+      expect(subject['definitions']['postRequestResponseItem']).to eql({
+        "description" => "post in body with entity",
+        "type"=>"object",
+        "properties"=>{
+          "name"=>{"type"=>"string", "description"=>"name"}},
+          "required"=>["name"]
+      })
+    end
+
+    specify do
+      expect(subject['paths']['/with_entities/in_body/{id}']['put']['parameters']).to eql([
+        {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
+        {"name"=>"ResponseItem", "in"=>"body", "required"=>true, "schema"=>{"$ref"=>"#/definitions/putRequestResponseItem"}}
+      ])
+    end
+
+    specify do
+      expect(subject['definitions']['putRequestResponseItem']).to eql({
+        "description" => "put in body with entity",
+        "type"=>"object",
+        "properties"=>{
+          "id"=>{"type"=>"integer", "format"=>"int32", "readOnly"=>true},
+          "name"=>{"type"=>"string", "description"=>"name"}}
+      })
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_param_type_spec.rb

@@ -0,0 +1,217 @@
+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 ParamTypeApi < Grape::API
+        # using `:param_type`
+        desc 'full set of request param types',
+          success: TheApi::Entities::UseResponse
+        params do
+          optional :in_query, type: String, documentation: { param_type: 'query' }
+          optional :in_header, type: String, documentation: { param_type: 'header' }
+        end
+
+        get '/defined_param_type' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'full set of request param types',
+          success: TheApi::Entities::UseResponse
+        params do
+          requires :in_path, type: Integer
+          optional :in_query, type: String, documentation: { param_type: 'query' }
+          optional :in_header, type: String, documentation: { param_type: 'header' }
+        end
+
+        get '/defined_param_type/:in_path' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'full set of request param types',
+          success: TheApi::Entities::UseResponse
+        params do
+          optional :in_path, type: Integer
+          optional :in_query, type: String, documentation: { param_type: 'query' }
+          optional :in_header, type: String, documentation: { param_type: 'header' }
+        end
+
+        delete '/defined_param_type/:in_path' do
+          { "declared_params" => declared(params) }
+        end
+
+        # using `:in`
+        desc 'full set of request param types using `:in`',
+          success: TheApi::Entities::UseResponse
+        params do
+          optional :in_query, type: String, documentation: { in: 'query' }
+          optional :in_header, type: String, documentation: { in: 'header' }
+        end
+
+        get '/defined_in' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'full set of request param types using `:in`',
+          success: TheApi::Entities::UseResponse
+        params do
+          requires :in_path, type: Integer
+          optional :in_query, type: String, documentation: { in: 'query' }
+          optional :in_header, type: String, documentation: { in: 'header' }
+        end
+
+        get '/defined_in/:in_path' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'full set of request param types using `:in`'
+        params do
+          optional :in_path, type: Integer
+          optional :in_query, type: String, documentation: { in: 'query' }
+          optional :in_header, type: String, documentation: { in: 'header' }
+        end
+
+        delete '/defined_in/:in_path' do
+          { "declared_params" => declared(params) }
+        end
+
+        # file
+        desc 'file download',
+          success: TheApi::Entities::UseResponse
+        params do
+          requires :name, type: String
+        end
+
+        get '/download' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'file upload',
+          success: TheApi::Entities::UseResponse
+        params do
+          requires :name, type: File
+        end
+
+        post '/upload' do
+          { "declared_params" => declared(params) }
+        end
+
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ParamTypeApi
+  end
+
+  describe 'foo' do
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type/{in_path}']['delete']['responses']).to eql({
+        "200"=>{"description"=>"full set of request param types", "schema"=>{"$ref"=>"#/definitions/UseResponse"}}
+      })
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in/{in_path}']['delete']['responses']).to eql({
+        "204"=>{"description"=>"full set of request param types using `:in`"}
+      })
+    end
+  end
+
+  describe 'defined param types' do
+    subject do
+      get '/swagger_doc/defined_param_type'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type']['get']['parameters']).to eql([
+        {"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
+        {"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
+      ])
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type/{in_path}']['get']['parameters']).to eql([
+        {"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
+        {"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
+        {"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
+      ])
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type/{in_path}']['delete']['parameters']).to eql([
+        {"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
+        {"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
+        {"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
+      ])
+    end
+  end
+
+  describe 'defined param types with `:in`' do
+    subject do
+      get '/swagger_doc/defined_in'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in']['get']['parameters']).to eql([
+        {"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
+        {"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
+      ])
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in/{in_path}']['get']['parameters']).to eql([
+        {"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
+        {"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
+        {"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
+      ])
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in/{in_path}']['delete']['parameters']).to eql([
+        {"in"=>"path", "name"=>"in_path", "description"=>nil, "required"=>true, "type"=>"integer", "format"=>"int32"},
+        {"in"=>"query", "name"=>"in_query", "description"=>nil, "required"=>false, "type"=>"string"},
+        {"in"=>"header", "name"=>"in_header", "description"=>nil, "required"=>false, "type"=>"string"},
+      ])
+    end
+  end
+
+  describe 'file' do
+    describe 'upload' do
+      subject do
+        get '/swagger_doc/upload'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']['/upload']['post']['parameters']).to eql([
+          {"in"=>"formData", "name"=>"name", "description"=>nil, "required"=>true, "type"=>"file"}
+        ])
+      end
+    end
+
+    describe 'download' do
+      subject do
+        get '/swagger_doc/download'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']['/download']['get']['parameters']).to eql([
+          {"in"=>"query", "name"=>"name", "description"=>nil, "required"=>true, "type"=>"string"}
+        ])
+      end
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe 'additional parameter settings' do
+  before :all do
+    module TheApi
+      class RequestParamFix < Grape::API
+        resource :bookings do
+          desc 'Update booking'
+          params do
+            optional :name, type: String
+          end
+          put ':id' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'Get booking details'
+          get ':id' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'Get booking details by access_number'
+          get '/conf/:access_number' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'Remove booking'
+          delete ':id' do
+            { "declared_params" => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::RequestParamFix
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject['paths']['/bookings/{id}']['put']['parameters']).to eql([
+      {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true},
+      {"in"=>"formData", "name"=>"name", "description"=>nil, "type"=>"string", "required"=>false}
+    ])
+  end
+
+  specify do
+    expect(subject['paths']['/bookings/{id}']['get']['parameters']).to eql([
+      {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}
+    ])
+  end
+
+  specify do
+    expect(subject['paths']['/bookings/{id}']['delete']['parameters']).to eql([
+      {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "format"=>"int32", "required"=>true}
+    ])
+  end
+end

data/spec/swagger_v2/api_swagger_v2_response_spec.rb

@@ -0,0 +1,184 @@
+require 'spec_helper'
+
+describe 'response' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class ResponseApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+          params: Entities::UseResponse.documentation,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        post '/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',
+          entity: Entities::UseItemResponseAsType,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        get '/nested_type' do
+          { "declared_params" => declared(params) }
+        end
+
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApi
+  end
+
+  describe "uses nested type as response object" do
+    subject do
+      get '/swagger_doc/nested_type'
+      JSON.parse(last_response.body)
+    end
+    specify do
+      expect(subject).to eql({
+        "info"=>{"title"=>"API title", "version"=>"v1"},
+        "swagger"=>"2.0",
+        "produces"=>["application/json"],
+        "host"=>"example.org",
+        "tags"=>[
+          {"name"=>"params_response", "description"=>"Operations about params_responses"},
+          {"name"=>"entity_response", "description"=>"Operations about entity_responses"},
+          {"name"=>"nested_type", "description"=>"Operations about nested_types"}
+        ],
+        "schemes"=>["https", "http"],
+        "paths"=>{
+          "/nested_type"=>{
+            "get"=>{
+              "description"=>"This returns something",
+              "produces"=>["application/json"],
+              "responses"=>{
+                "200"=>{"description"=>"This returns something", "schema"=>{"$ref"=>"#/definitions/UseItemResponseAsType"}},
+                "400"=>{"description"=>"NotFound", "schema"=>{"$ref"=>"#/definitions/ApiError"}}
+              },
+              "tags"=>["nested_type"],
+              "operationId"=>"getNestedType"
+        }}},
+        "definitions"=>{
+          "ResponseItem"=>{
+            "type"=>"object",
+            "properties"=>{"id"=>{"type"=>"integer", "format"=>"int32"}, "name"=>{"type"=>"string"}}
+          },
+          "UseItemResponseAsType"=>{
+            "type"=>"object",
+            "properties"=>{"description"=>{"type"=>"string"}, "responses"=>{"$ref"=>"#/definitions/ResponseItem"}},
+            "description"=>"This returns something"
+          },
+          "ApiError"=>{
+            "type"=>"object",
+            "properties"=>{"code"=>{"type"=>"integer", "format"=>"int32"}, "message"=>{"type"=>"string"}},
+            "description"=>"This returns something"
+          }}
+        })
+    end
+  end
+
+  describe "uses entity as response object" do
+    subject do
+      get '/swagger_doc/entity_response'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to eql({
+        "info"=>{"title"=>"API title", "version"=>"v1"},
+        "swagger"=>"2.0",
+        "produces"=>["application/json"],
+        "host"=>"example.org",
+        "tags" => [
+          {"name"=>"params_response", "description"=>"Operations about params_responses"},
+          {"name"=>"entity_response", "description"=>"Operations about entity_responses"},
+          {"name"=>"nested_type", "description"=>"Operations about nested_types"}
+        ],
+        "schemes"=>["https", "http"],
+        "paths"=>{
+          "/entity_response"=>{
+            "get"=>{
+              "description"=>"This returns something",
+              "produces"=>["application/json"],
+              "tags"=>["entity_response"],
+              "operationId"=>"getEntityResponse",
+              "responses"=>{
+                "200"=>{"description"=>"This returns something", "schema"=>{"$ref"=>"#/definitions/UseResponse"}},
+                "400"=>{"description"=>"NotFound", "schema"=>{"$ref"=>"#/definitions/ApiError"}}}}}},
+        "definitions"=>{
+          "ResponseItem"=>{
+            "type"=>"object",
+            "properties"=>{"id"=>{"type"=>"integer", "format"=>"int32"}, "name"=>{"type"=>"string"}}},
+          "UseResponse"=>{
+            "type"=>"object",
+            "properties"=>{"description"=>{"type"=>"string"}, "$responses"=>{"type"=>"array", "items"=>{"$ref"=>"#/definitions/ResponseItem"}}},
+            "description"=>"This returns something"
+          },
+          "ApiError"=>{
+            "type"=>"object",
+            "properties"=>{"code"=>{"type"=>"integer", "format"=>"int32"}, "message"=>{"type"=>"string"}},
+            "description"=>"This returns something"
+          }
+      }})
+    end
+  end
+
+  describe "uses params as response object" do
+    subject do
+      get '/swagger_doc/params_response'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to eql({
+        "info"=>{"title"=>"API title", "version"=>"v1"},
+        "swagger"=>"2.0",
+        "produces"=>["application/json"],
+        "host"=>"example.org",
+        "tags" => [
+          {"name"=>"params_response", "description"=>"Operations about params_responses"},
+          {"name"=>"entity_response", "description"=>"Operations about entity_responses"},
+          {"name"=>"nested_type", "description"=>"Operations about nested_types"}
+        ],
+        "schemes"=>["https", "http"],
+        "paths"=>{
+          "/params_response"=>{
+            "post"=>{
+              "description"=>"This returns something",
+              "produces"=>["application/json"],
+              "consumes"=>["application/json"],
+              "parameters"=>[
+                {"in"=>"formData", "name"=>"description", "description"=>nil, "type"=>"string", "required"=>false},
+                {"in"=>"formData", "name"=>"$responses", "description"=>nil, "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
+              "tags"=>["params_response"],
+              "operationId"=>"postParamsResponse",
+              "responses"=>{
+                "201"=>{"description"=>"This returns something", "schema"=>{"$ref"=>"#/definitions/ParamsResponse"}},
+                "400"=>{"description"=>"NotFound", "schema"=>{"$ref"=>"#/definitions/ApiError"}}}
+        }}},
+        "definitions"=>{
+          "ParamsResponse"=>{
+            "type"=>"object",
+            "properties"=>{"description"=>{"type"=>"string"}, "$responses"=>{"type"=>"string"}},
+            "description"=>"This returns something"
+          },
+          "ApiError"=>{
+            "type"=>"object",
+            "properties"=>{"code"=>{"type"=>"integer", "format"=>"int32"}, "message"=>{"type"=>"string"}},
+            "description"=>"This returns something"
+          }
+      }})
+    end
+  end
+
+end