grape-swagger 0.11.0 → 0.20.0

data/spec/swagger_v2/response_model_spec.rb

@@ -0,0 +1,212 @@
+require 'spec_helper'
+
+describe 'responseModel' do
+  before :all do
+    module ThisApi
+      module Entities
+        class Kind < Grape::Entity
+          expose :title, documentation: { type: 'string', desc: 'Title of the kind.' }
+        end
+
+        class Relation < Grape::Entity
+          expose :name, documentation: { type: 'string', desc: 'Name' }
+
+        end
+        class Tag < Grape::Entity
+          expose :name, documentation: { type: 'string', desc: 'Name' }
+
+        end
+        class Error < Grape::Entity
+          expose :code, documentation: { type: 'string', desc: 'Error code' }
+          expose :message, documentation: { type: 'string', desc: 'Error message' }
+        end
+
+        class Something < Grape::Entity
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+          expose :kind, using: Kind, documentation: { type: 'ThisApi::Kind', desc: 'The kind of this something.' }
+          expose :kind2, using: Kind, documentation: { desc: 'Secondary kind.' }
+          expose :kind3, using: ThisApi::Entities::Kind, documentation: { desc: 'Tertiary kind.' }
+          expose :tags, using: ThisApi::Entities::Tag, documentation: { desc: 'Tags.', is_array: true }
+          expose :relation, using: ThisApi::Entities::Relation, documentation: { type: 'ThisApi::Relation', desc: 'A related model.' }
+        end
+      end
+
+      class ResponseModelApi < Grape::API
+        format :json
+        desc 'This returns something',
+          is_array: true,
+          http_codes: [ { code: 200, message: 'OK', model: Entities::Something } ]
+        get '/something' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        # something like an index action
+        desc 'This returns something or an error',
+             entity: Entities::Something,
+             http_codes: [
+               { code: 200, message: 'OK', model: Entities::Something },
+               { code: 403, message: 'Refused to return something', model: Entities::Error }
+             ]
+        params do
+          optional :id, type: Integer
+        end
+        get '/something/:id' do
+          if params[:id] == 1
+            something = OpenStruct.new text: 'something'
+            present something, with: Entities::Something
+          else
+            error = OpenStruct.new code: 'some_error', message: 'Some error'
+            present error, with: Entities::Error
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    ThisApi::ResponseModelApi
+  end
+
+  subject do
+    get '/swagger_doc/something'
+    JSON.parse(last_response.body)
+  end
+
+  it "documents index action" do
+    expect(subject['paths']["/something"]["get"]["responses"]).to eq(
+      {
+        "200"=>{
+          "description"=>"OK",
+          "schema"=>{
+            "type"=>"array",
+            "items"=>{"$ref"=>"#/definitions/Something"}}
+        }}
+    )
+  end
+
+  it 'should document specified models as show action' do
+    expect(subject['paths']["/something/{id}"]["get"]["responses"]).to eq(
+      {
+        "200"=>{
+          "description"=>"OK",
+          "schema"=>{"$ref"=>"#/definitions/Something"}
+        },
+        "403"=>{
+          "description"=>"Refused to return something",
+          "schema"=>{"$ref"=>"#/definitions/Error"}
+      }}
+    )
+    expect(subject['definitions'].keys).to include 'Error'
+    expect(subject['definitions']['Error']).to eq(
+      {
+        "type"=>"object",
+        "description" => "This returns something or an error",
+        "properties"=>{
+          "code"=>{"type"=>"string"},
+          "message"=>{"type"=>"string"}
+      }}
+    )
+
+    expect(subject['definitions'].keys).to include 'Something'
+    expect(subject['definitions']['Something']).to eq(
+    { "type"=>"object",
+      "description" => "This returns something or an error",
+      "properties"=>
+        { "text"=>{"type"=>"string"},
+          "kind"=>{"$ref"=>"#/definitions/Kind"},
+          "kind2"=>{"$ref"=>"#/definitions/Kind"},
+          "kind3"=>{"$ref"=>"#/definitions/Kind"},
+          "tags"=>{"type"=>"array", "items"=>{"$ref"=>"#/definitions/Tag"}},
+          "relation"=>{"$ref"=>"#/definitions/Relation"}}}
+    )
+
+    expect(subject['definitions'].keys).to include 'Kind'
+    expect(subject['definitions']['Kind']).to eq(
+      "type"=>"object", "properties"=>{"title"=>{"type"=>"string"}}
+    )
+
+    expect(subject['definitions'].keys).to include 'Relation'
+    expect(subject['definitions']['Relation']).to eq(
+      "type"=>"object", "properties"=>{"name"=>{"type"=>"string"}}
+    )
+
+    expect(subject['definitions'].keys).to include 'Tag'
+    expect(subject['definitions']['Tag']).to eq(
+      "type"=>"object", "properties"=>{"name"=>{"type"=>"string"}}
+    )
+  end
+end
+
+describe 'should build definition from given entity' do
+  before :all do
+    module TheseApi
+      module Entities
+        class Kind < Grape::Entity
+          expose :id, documentation: { type: Integer, desc: 'Title of the kind.' }
+        end
+
+        class Relation < Grape::Entity
+          expose :name, documentation: { type: String, desc: 'Name' }
+
+        end
+        class Tag < Grape::Entity
+          expose :name, documentation: { type: 'string', desc: 'Name' }
+
+        end
+
+        class SomeEntity < Grape::Entity
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+          expose :kind, using: Kind, documentation: { type: 'TheseApi::Kind', desc: 'The kind of this something.' }
+          expose :kind2, using: Kind, documentation: { desc: 'Secondary kind.' }
+          expose :kind3, using: TheseApi::Entities::Kind, documentation: { desc: 'Tertiary kind.' }
+          expose :tags, using: TheseApi::Entities::Tag, documentation: { desc: 'Tags.', is_array: true }
+          expose :relation, using: TheseApi::Entities::Relation, documentation: { type: 'TheseApi::Relation', desc: 'A related model.' }
+        end
+      end
+
+      class ResponseEntityApi < Grape::API
+        format :json
+        desc 'This returns something',
+          is_array: true,
+          entity: Entities::SomeEntity
+        get '/some_entity' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::SomeEntity
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheseApi::ResponseEntityApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  it "it prefer entity over others" do
+    expect(subject['definitions']).to eql({
+      "Kind"=>{"type"=>"object", "properties"=>{"id"=>{"type"=>"integer", "format"=>"int32"}}},
+      "Tag"=>{"type"=>"object", "properties"=>{"name"=>{"type"=>"string"}}},
+      "Relation"=>{"type"=>"object", "properties"=>{"name"=>{"type"=>"string"}}},
+      "SomeEntity"=>{
+        "type"=>"object",
+        "properties"=>{
+          "text"=>{"type"=>"string"},
+          "kind"=>{"$ref"=>"#/definitions/Kind"},
+          "kind2"=>{"$ref"=>"#/definitions/Kind"},
+          "kind3"=>{"$ref"=>"#/definitions/Kind"},
+          "tags"=>{"type"=>"array", "items"=>{"$ref"=>"#/definitions/Tag"}},
+          "relation"=>{"$ref"=>"#/definitions/Relation"}
+        },
+        "description"=>"This returns something"
+      }})
+  end
+end

data/spec/swagger_v2/simple_mounted_api_spec.rb

@@ -0,0 +1,264 @@
+require 'spec_helper'
+
+describe 'a simple mounted api' do
+  before :all do
+    class CustomType; end
+
+    class SimpleMountedApi < Grape::API
+      desc 'Document root'
+      get do
+      end
+
+      desc 'This gets something.',
+        notes: '_test_'
+
+      get '/simple' do
+        { bla: 'something' }
+      end
+
+      desc 'This gets something for URL using - separator.',
+        notes: '_test_'
+
+      get '/simple-test' do
+        { bla: 'something' }
+      end
+
+      desc 'this gets something else',
+        headers: {
+          'XAuthToken' => { description: 'A required header.', required: true },
+          'XOtherHeader' => { description: 'An optional header.', required: false }
+        },
+        http_codes: [
+          { code: 403, message: 'invalid pony' },
+          { code: 405, message: 'no ponies left!' }
+        ]
+
+      get '/simple_with_headers' do
+        { bla: 'something_else' }
+      end
+
+      desc 'this takes an array of parameters',
+        params: {
+          'items[]' => { description: 'array of items', is_array: true }
+        }
+
+      post '/items' do
+        {}
+      end
+
+      desc 'this uses a custom parameter',
+        params: {
+          'custom' => { type: CustomType, description: 'array of items', is_array: true }
+        }
+
+      get '/custom' do
+        {}
+      end
+    end
+
+    class SimpleApi < Grape::API
+      mount SimpleMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    SimpleApi
+  end
+
+  describe "retrieves swagger-documentation on /swagger_doc" do
+    subject do
+      get '/swagger_doc.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to eq({
+        "info"=>{"title"=>"API title", "version"=>"v1"},
+        "swagger"=>"2.0",
+        "produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
+        "host"=>"example.org",
+        "tags" => [{"name"=>"simple", "description"=>"Operations about simples"}, {"name"=>"simple-test", "description"=>"Operations about simple-tests"}, {"name"=>"simple_with_headers", "description"=>"Operations about simple_with_headers"}, {"name"=>"items", "description"=>"Operations about items"}, {"name"=>"custom", "description"=>"Operations about customs"}],
+        "schemes"=>["https", "http"],
+        "paths"=>{
+          "/simple"=>{
+            "get"=>{
+              "description"=>"This gets something.",
+              "produces"=>["application/json"],
+              "tags"=>["simple"],
+              "operationId"=>"getSimple",
+              "responses"=>{"200"=>{"description"=>"This gets something."}}}},
+          "/simple-test"=>{
+            "get"=>{
+              "description"=>"This gets something for URL using - separator.",
+              "produces"=>["application/json"],
+              "tags"=>["simple-test"],
+              "operationId"=>"getSimpleTest",
+              "responses"=>{"200"=>{"description"=>"This gets something for URL using - separator."}}}},
+          "/simple_with_headers"=>{
+            "get"=>{
+              "description"=>"this gets something else",
+              "headers"=>{
+                "XAuthToken"=>{"description"=>"A required header.", "required"=>true},
+                "XOtherHeader"=>{"description"=>"An optional header.", "required"=>false}},
+              "produces"=>["application/json"],
+              "tags"=>["simple_with_headers"],
+              "operationId"=>"getSimpleWithHeaders",
+              "responses"=>{
+                "200"=>{"description"=>"this gets something else"},
+                "403"=>{"description"=>"invalid pony"},
+                "405"=>{"description"=>"no ponies left!"}}
+          }},
+          "/items"=>{
+            "post"=>{
+              "description"=>"this takes an array of parameters",
+              "produces"=>["application/json"],
+              "consumes"=>["application/json"],
+              "parameters"=>[{"in"=>"formData", "name"=>"items[]", "description"=>"array of items", "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
+              "tags"=>["items"],
+              "operationId"=>"postItems",
+              "responses"=>{"201"=>{"description"=>"this takes an array of parameters", "schema"=>{"$ref"=>"#/definitions/Item"}}}
+          }},
+          "/custom"=>{
+            "get"=>{
+              "description"=>"this uses a custom parameter",
+              "produces"=>["application/json"],
+              "parameters"=>[{"in"=>"formData", "name"=>"custom", "description"=>"array of items", "required"=>false, "type"=>"array", "items"=>{"type"=>"CustomType"}}],
+              "tags"=>["custom"],
+              "operationId"=>"getCustom",
+              "responses"=>{"200"=>{"description"=>"this uses a custom parameter", "schema"=>{"$ref"=>"#/definitions/Custom"}}}}
+      }},
+      "definitions"=>{
+        "Item"=>{
+          "type"=>"object",
+          "properties"=>{"items[]"=>{"type"=>"string"}},
+          "description"=>"this takes an array of parameters"
+        },
+        "Custom"=>{
+          "type"=>"object",
+          "properties"=>{"custom"=>{"type"=>"CustomType"}},
+          "description"=>"this uses a custom parameter"
+        }}})
+    end
+  end
+
+  describe 'retrieves the documentation for mounted-api' do
+    subject do
+      get '/swagger_doc/simple.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to eq({
+        "info"=>{"title"=>"API title", "version"=>"v1"},
+        "swagger"=>"2.0",
+        "produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
+        "host"=>"example.org",
+        "tags" => [{"name"=>"simple", "description"=>"Operations about simples"}, {"name"=>"simple-test", "description"=>"Operations about simple-tests"}, {"name"=>"simple_with_headers", "description"=>"Operations about simple_with_headers"}, {"name"=>"items", "description"=>"Operations about items"}, {"name"=>"custom", "description"=>"Operations about customs"}],
+        "schemes"=>["https", "http"],
+        "paths"=>{
+          "/simple"=>{
+            "get"=>{
+              "description"=>"This gets something.",
+              "produces"=>["application/json"],
+              "tags"=>["simple"],
+              "operationId"=>"getSimple",
+              "responses"=>{"200"=>{"description"=>"This gets something."}}}}
+        }})
+    end
+  end
+
+  describe 'retrieves the documentation for mounted-api that' do
+    describe "contains '-' in URL" do
+      subject do
+        get '/swagger_doc/simple-test.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject).to eq({
+          "info"=>{"title"=>"API title", "version"=>"v1"},
+          "swagger"=>"2.0",
+          "produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
+          "host"=>"example.org",
+          "tags" => [{"name"=>"simple", "description"=>"Operations about simples"}, {"name"=>"simple-test", "description"=>"Operations about simple-tests"}, {"name"=>"simple_with_headers", "description"=>"Operations about simple_with_headers"}, {"name"=>"items", "description"=>"Operations about items"}, {"name"=>"custom", "description"=>"Operations about customs"}],
+          "schemes"=>["https", "http"],
+          "paths"=>{
+            "/simple-test"=>{
+              "get"=>{
+                "description"=>"This gets something for URL using - separator.",
+                "produces"=>["application/json"],
+                "tags"=>["simple-test"],
+                "operationId"=>"getSimpleTest",
+                "responses"=>{"200"=>{"description"=>"This gets something for URL using - separator."}}}}
+          }})
+      end
+    end
+
+    describe 'includes headers' do
+      subject do
+        get '/swagger_doc/simple_with_headers.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']).to eq({
+          "/simple_with_headers"=>{
+            "get"=>{
+              "description"=>"this gets something else",
+              "headers"=>{
+                "XAuthToken"=>{"description"=>"A required header.", "required"=>true},
+                "XOtherHeader"=>{"description"=>"An optional header.", "required"=>false}},
+              "produces"=>["application/json"],
+              "tags"=>["simple_with_headers"],
+              "operationId"=>"getSimpleWithHeaders",
+              "responses"=>{
+                "200"=>{"description"=>"this gets something else"},
+                "403"=>{"description"=>"invalid pony"},
+                "405"=>{"description"=>"no ponies left!"}}}
+          }})
+      end
+    end
+
+    describe 'supports array params' do
+      subject do
+        get '/swagger_doc/items.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']).to eq({
+          "/items"=>{
+            "post"=>{
+              "description"=>"this takes an array of parameters",
+              "produces"=>["application/json"],
+              "consumes"=>["application/json"],
+              "parameters"=>[{"in"=>"formData", "name"=>"items[]", "description"=>"array of items", "required"=>false, "type"=>"array", "items"=>{"type"=>"string"}}],
+              "tags"=>["items"],
+              "operationId"=>"postItems",
+              "responses"=>{"201"=>{"description"=>"this takes an array of parameters", "schema"=>{"$ref"=>"#/definitions/Item"}}}}
+          }})
+      end
+    end
+
+    describe 'supports custom params types' do
+      subject do
+        get '/swagger_doc/custom.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']).to eq({
+          "/custom"=>{
+            "get"=>{
+              "description"=>"this uses a custom parameter",
+              "produces"=>["application/json"],
+              "parameters"=>[{"in"=>"formData", "name"=>"custom", "description"=>"array of items", "required"=>false, "type"=>"array", "items"=>{"type"=>"CustomType"}}],
+              "tags"=>["custom"],
+              "operationId"=>"getCustom",
+              "responses"=>{"200"=>{"description"=>"this uses a custom parameter", "schema"=>{"$ref"=>"#/definitions/Custom"}}}}
+          }})
+      end
+    end
+  end
+end