grape-swagger 0.11.0 → 0.20.0

data/spec/swagger_v2/description_not_initialized.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe 'details' do
+  describe 'details, pass markdown with redcarpet even with nil description and detail', unless: RUBY_PLATFORM.eql?('java') do
+    include_context "the api entities"
+
+    before :all do
+      module TheApi
+        class GfmRcDetailApi < Grape::API
+          format :json
+
+          desc nil,
+               detail: nil,
+               entity: Entities::UseResponse,
+               failure: [{code: 400, model: Entities::ApiError}]
+          get '/use_gfm_rc_detail' do
+            { "declared_params" => declared(params) }
+          end
+
+          add_swagger_documentation markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
+        end
+      end
+    end
+
+    def app
+      TheApi::GfmRcDetailApi
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_gfm_rc_detail']['get']).not_to include('description')
+      expect(subject['paths']['/use_gfm_rc_detail']['get']['description']).to eql(nil)
+    end
+  end
+end

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

@@ -19,12 +19,12 @@ describe 'Float 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 float types' do
     expect(subject).to eq [
-      { 'paramType' => 'form', 'name' => 'a_float', 'description' => '', 'type' => 'number', 'format' => 'float', 'required' => true, 'allowMultiple' => false }
+      {"in"=>"formData", "name"=>"a_float", "description"=>nil, "type"=>"number", "required"=>true, "format"=>"float"}
     ]
   end
 end

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

@@ -49,17 +49,17 @@ describe 'Form Params' do
   end
 
   it 'retrieves the documentation form params' do
-    expect(subject['apis'].count).to eq 2
-    expect(subject['apis'][0]['path']).to start_with '/items'
-    expect(subject['apis'][0]['operations'][0]['method']).to eq 'POST'
-    expect(subject['apis'][1]['path']).to start_with '/items/{id}'
-    expect(subject['apis'][1]['operations'][0]['method']).to eq 'PUT'
-    expect(subject['apis'][1]['operations'][1]['method']).to eq 'PATCH'
-    expect(subject['apis'][1]['operations'][2]['method']).to eq 'POST'
+    expect(subject['paths'].length).to eq 2
+    expect(subject['paths'].keys).to include('/items','/items/{id}')
+    expect(subject['paths']['/items'].keys).to include 'post'
+    expect(subject['paths']['/items/{id}'].keys).to include('post', 'patch', 'put')
   end
 
   it 'treats Symbol parameter as form param' do
-    expect(subject['apis'][1]['operations'][2]['parameters'][2]['paramType']).to eq 'form'
-    expect(subject['apis'][1]['operations'][2]['parameters'][2]['type']).to eq 'string'
+    expect(subject['paths']['/items/{id}']['post']['parameters']).to eq [
+      {"in"=>"path", "name"=>"id", "description"=>"id of item", "type"=>"integer", "required"=>true, "format"=>"int32"},
+      {"in"=>"formData", "name"=>"name", "description"=>"name of item", "type"=>"string", "required"=>true},
+      {"in"=>"formData", "name"=>"conditions", "description"=>"conditions of item", "type"=>"string", "required"=>false, "enum"=>["one", "two"]}
+    ]
   end
 end

data/spec/swagger_v2/hide_api_spec.rb

@@ -0,0 +1,131 @@
+require 'spec_helper'
+
+describe 'a hide mounted api' do
+  before :all do
+    class HideMountedApi < Grape::API
+      desc 'Show this endpoint'
+      get '/simple' do
+        { foo: 'bar' }
+      end
+
+      desc 'Hide this endpoint', hidden: true
+      get '/hide' do
+        { foo: 'bar' }
+      end
+
+      desc 'Lazily show endpoint', hidden: -> { false }
+      get '/lazy' do
+        { foo: 'bar' }
+      end
+    end
+
+    class HideApi < Grape::API
+      mount HideMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    HideApi
+  end
+
+  subject do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body)
+  end
+
+  it "retrieves swagger-documentation that doesn't include hidden endpoints" 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"=>"lazy", "description"=>"Operations about lazies"}],
+      "schemes" => ["https", "http"],
+      "paths"=>{
+        "/simple"=>{
+          "get"=>{
+            "description"=>"Show this endpoint",
+            "produces"=>["application/json"],
+            "tags"=>["simple"],
+            "operationId"=>"getSimple",
+            "responses"=>{"200"=>{"description"=>"Show this endpoint"}}}},
+        "/lazy"=>{
+          "get"=>{
+            "description"=>"Lazily show endpoint",
+            "produces"=>["application/json"],
+            "tags"=>["lazy"],
+            "operationId"=>"getLazy",
+            "responses"=>{"200"=>{"description"=>"Lazily show endpoint"}}}}}
+    })
+  end
+end
+
+describe 'a hide mounted api with same namespace' do
+  before :all do
+    class HideNamespaceMountedApi < Grape::API
+      desc 'Show this endpoint'
+      get '/simple/show' do
+        { foo: 'bar' }
+      end
+
+      desc 'Hide this endpoint', hidden: true
+      get '/simple/hide' do
+        { foo: 'bar' }
+      end
+
+      desc 'Lazily hide endpoint', hidden: -> { true }
+      get '/simple/lazy' do
+        { foo: 'bar' }
+      end
+    end
+
+    class HideNamespaceApi < Grape::API
+      mount HideNamespaceMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    HideNamespaceApi
+  end
+
+  it 'retrieves swagger-documentation on /swagger_doc' do
+    get '/swagger_doc.json'
+    expect(JSON.parse(last_response.body)).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"}],
+      "schemes" => ["https", "http"],
+      "paths"=>{
+        "/simple/show"=>{
+          "get"=>{
+            "description"=>"Show this endpoint",
+            "produces"=>["application/json"],
+            "operationId"=>"getSimpleShow",
+            "tags"=>["simple"], "responses"=>{"200"=>{"description"=>"Show this endpoint"}}}}}
+      })
+  end
+
+  it "retrieves the documentation for mounted-api that doesn't include hidden endpoints" do
+    get '/swagger_doc/simple.json'
+    expect(JSON.parse(last_response.body)).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"}],
+      "schemes" => ["https", "http"],
+      "paths"=>{
+        "/simple/show"=>{
+          "get"=>{
+            "description"=>"Show this endpoint",
+            "produces"=>["application/json"],
+            "tags"=>["simple"],
+            "operationId"=>"getSimpleShow",
+            "responses"=>{"200"=>{"description"=>"Show this endpoint"}}}}}
+      })
+  end
+end

data/spec/swagger_v2/mounted_target_class_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe 'docs mounted separately from api' do
+  before :all do
+    class ActualApi < Grape::API
+      desc 'Document root'
+
+      desc 'This gets something.',
+           notes: '_test_'
+      get '/simple' do
+        { bla: 'something' }
+      end
+    end
+
+    class MountedDocs < Grape::API
+      add_swagger_documentation(target_class: ActualApi)
+    end
+
+    class WholeApp < Grape::API
+      mount ActualApi
+      mount MountedDocs
+    end
+  end
+
+  def app
+    WholeApp
+  end
+
+  it 'retrieves docs for actual api class' do
+    get '/swagger_doc.json'
+    expect(JSON.parse(last_response.body)).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"}],
+      "schemes"=>["https", "http"],
+      "paths"=>{
+        "/simple"=>{
+          "get"=>{
+            "description"=>"This gets something.",
+            "produces"=>["application/json"],
+            "responses"=>{"200"=>{"description"=>"This gets something."}},
+            "tags"=>["simple"],
+            "operationId"=>"getSimple"
+          }
+        }
+      }
+    })
+  end
+
+  it 'retrieves docs for endpoint in actual api class' do
+    get '/swagger_doc/simple.json'
+    expect(JSON.parse(last_response.body)).to eq({
+      "info"=>{"title"=>"API title", "version"=>"v1"},
+      "swagger"=>"2.0",
+      "tags" => [{"name"=>"simple", "description"=>"Operations about simples"}],
+      "produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
+      "host"=>"example.org",
+      "schemes" => ["https", "http"],
+      "paths" => {
+        "/simple"=>{
+          "get"=>{
+            "description"=>"This gets something.",
+            "produces"=>["application/json"],
+            "responses"=>{
+              "200"=>{"description"=>"This gets something."}
+            },
+            "tags"=>["simple"],
+            "operationId"=>"getSimple"
+          }
+        }
+      }
+    })
+  end
+end

data/spec/swagger_v2/namespace_tags_prefix_spec.rb

@@ -0,0 +1,84 @@
+require 'spec_helper'
+
+describe 'namespace tags check while using prefix and version' do
+  include_context "namespace example"
+
+  before :all do
+    module TheApi
+      class NamespaceApi < Grape::API
+        version :v1
+      end
+    end
+
+    class TagApi < Grape::API
+      prefix :api
+      mount TheApi::NamespaceApi
+      add_swagger_documentation version: 'v1'
+    end
+  end
+
+  def app
+    TagApi
+  end
+
+  describe "retrieves swagger-documentation on /swagger_doc" do
+    subject do
+      get '/api/swagger_doc.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['tags']).to eql([
+        {"name"=>"hudson", "description"=>"Operations about hudsons"},
+        {"name"=>"colorado", "description"=>"Operations about colorados"},
+        {"name"=>"thames", "description"=>"Operations about thames"},
+        {"name"=>"niles", "description"=>"Operations about niles"}
+      ])
+
+      expect(subject['paths']['/api/v1/hudson']['get']['tags']).to eql(['hudson'])
+      expect(subject['paths']['/api/v1/colorado/simple']['get']['tags']).to eql(['colorado'])
+      expect(subject['paths']['/api/v1/colorado/simple-test']['get']['tags']).to eql(['colorado'])
+      expect(subject['paths']['/api/v1/thames/simple_with_headers']['get']['tags']).to eql(['thames'])
+      expect(subject['paths']['/api/v1/niles/items']['post']['tags']).to eql(['niles'])
+      expect(subject['paths']['/api/v1/niles/custom']['get']['tags']).to eql(['niles'])
+    end
+  end
+
+
+  describe 'retrieves the documentation for mounted-api' do
+    subject do
+      get '/api/swagger_doc/colorado.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['tags']).to eql([
+        {"name"=>"hudson", "description"=>"Operations about hudsons"},
+        {"name"=>"colorado", "description"=>"Operations about colorados"},
+        {"name"=>"thames", "description"=>"Operations about thames"},
+        {"name"=>"niles", "description"=>"Operations about niles"}
+      ])
+
+      expect(subject['paths']['/api/v1/colorado/simple']['get']['tags']).to eql(['colorado'])
+      expect(subject['paths']['/api/v1/colorado/simple-test']['get']['tags']).to eql(['colorado'])
+    end
+
+    describe 'includes headers' do
+      subject do
+        get '/api/swagger_doc/thames.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['tags']).to eql([
+          {"name"=>"hudson", "description"=>"Operations about hudsons"},
+          {"name"=>"colorado", "description"=>"Operations about colorados"},
+          {"name"=>"thames", "description"=>"Operations about thames"},
+          {"name"=>"niles", "description"=>"Operations about niles"}
+        ])
+
+        expect(subject['paths']['/api/v1/thames/simple_with_headers']['get']['tags']).to eql(['thames'])
+      end
+    end
+  end
+end

data/spec/swagger_v2/namespace_tags_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe 'namespace tags check' do
+  include_context "namespace example"
+
+  before :all do
+    class TestApi < Grape::API
+      mount TheApi::NamespaceApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    TestApi
+  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['tags']).to eql([
+        {"name"=>"hudson", "description"=>"Operations about hudsons"},
+        {"name"=>"colorado", "description"=>"Operations about colorados"},
+        {"name"=>"thames", "description"=>"Operations about thames"},
+        {"name"=>"niles", "description"=>"Operations about niles"}
+      ])
+
+      expect(subject['paths']['/hudson']['get']['tags']).to eql(['hudson'])
+      expect(subject['paths']['/colorado/simple']['get']['tags']).to eql(['colorado'])
+      expect(subject['paths']['/colorado/simple-test']['get']['tags']).to eql(['colorado'])
+      expect(subject['paths']['/thames/simple_with_headers']['get']['tags']).to eql(['thames'])
+      expect(subject['paths']['/niles/items']['post']['tags']).to eql(['niles'])
+      expect(subject['paths']['/niles/custom']['get']['tags']).to eql(['niles'])
+    end
+  end
+
+  describe 'retrieves the documentation for mounted-api' do
+    subject do
+      get '/swagger_doc/colorado.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['tags']).to eql([
+        {"name"=>"hudson", "description"=>"Operations about hudsons"},
+        {"name"=>"colorado", "description"=>"Operations about colorados"},
+        {"name"=>"thames", "description"=>"Operations about thames"},
+        {"name"=>"niles", "description"=>"Operations about niles"}
+      ])
+
+      expect(subject['paths']['/colorado/simple']['get']['tags']).to eql(['colorado'])
+      expect(subject['paths']['/colorado/simple-test']['get']['tags']).to eql(['colorado'])
+    end
+
+    describe 'includes headers' do
+      subject do
+        get '/swagger_doc/thames.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['tags']).to eql([
+          {"name"=>"hudson", "description"=>"Operations about hudsons"},
+          {"name"=>"colorado", "description"=>"Operations about colorados"},
+          {"name"=>"thames", "description"=>"Operations about thames"},
+          {"name"=>"niles", "description"=>"Operations about niles"}
+        ])
+
+        expect(subject['paths']['/thames/simple_with_headers']['get']['tags']).to eql(['thames'])
+      end
+    end
+  end
+end