grape-swagger 0.7.2 → 0.8.0

data/spec/hide_api_spec.rb

@@ -1,18 +1,18 @@
 require 'spec_helper'
 
-describe "a hide mounted api" do
+describe 'a hide mounted api' do
   before :all do
     class HideMountedApi < Grape::API
       desc 'Show this endpoint'
       get '/simple' do
-        { :foo => 'bar' }
+        { foo: 'bar' }
       end
 
-      desc 'Hide this endpoint', {
-        :hidden => true
-      }
+      desc 'Hide this endpoint',
+           hidden: true
+
       get '/hide' do
-        { :foo => 'bar' }
+        { foo: 'bar' }
       end
     end
 
@@ -22,39 +22,42 @@ describe "a hide mounted api" do
     end
   end
 
-  def app; HideApi end
+  def app
+    HideApi
+  end
 
-  it "retrieves swagger-documentation that doesn't include hidden endpoints" do
+  subject do
     get '/swagger_doc.json'
-    JSON.parse(last_response.body).should == {
-      "apiVersion" => "0.1",
-      "swaggerVersion" => "1.2",
-      "basePath" => "http://example.org",
-      "info" => {},
-      "produces" => ["application/xml", "application/json", "text/plain"],
-      "operations" => [],
-      "apis" => [
-        { "path" => "/swagger_doc/simple.{format}" },
-        { "path" => "/swagger_doc/swagger_doc.{format}" }
+    JSON.parse(last_response.body)
+  end
+
+  it "retrieves swagger-documentation that doesn't include hidden endpoints" do
+    expect(subject).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'info' => {},
+      'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+      'apis' => [
+        { 'path' => '/simple.{format}', 'description' => 'Operations about simples' },
+        { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
       ]
-    }
+    )
   end
 end
 
-
-describe "a hide mounted api with same namespace" do
+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' }
+        { foo: 'bar' }
       end
 
-      desc 'Hide this endpoint', {
-        :hidden => true
-      }
+      desc 'Hide this endpoint',
+           hidden: true
+
       get '/simple/hide' do
-        { :foo => 'bar' }
+        { foo: 'bar' }
       end
     end
 
@@ -64,43 +67,43 @@ describe "a hide mounted api with same namespace" do
     end
   end
 
-  def app; HideNamespaceApi end
+  def app
+    HideNamespaceApi
+  end
 
-  it "retrieves swagger-documentation on /swagger_doc" do
+  it 'retrieves swagger-documentation on /swagger_doc' do
     get '/swagger_doc.json'
-    JSON.parse(last_response.body).should == {
-      "apiVersion" => "0.1",
-      "swaggerVersion" => "1.2",
-      "basePath" => "http://example.org",
-      "info" => {},
-      "produces" => ["application/xml", "application/json", "text/plain"],
-      "operations" => [],
-      "apis" => [
-        { "path" => "/swagger_doc/simple.{format}" },
-        { "path" => "/swagger_doc/swagger_doc.{format}" }
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'info' => {},
+      'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+      'apis' => [
+        { 'path' => '/simple.{format}', 'description' => 'Operations about simples' },
+        { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
       ]
-    }
+    )
   end
 
   it "retrieves the documentation for mounted-api that doesn't include hidden endpoints" do
     get '/swagger_doc/simple.json'
-    JSON.parse(last_response.body).should == {
-      "apiVersion" => "0.1",
-      "swaggerVersion" => "1.2",
-      "basePath" => "http://example.org",
-      "resourcePath" => "",
-      "apis" => [{
-        "path" => "/simple/show.{format}",
-        "operations" => [{
-          "produces" => ["application/xml", "application/json", "text/plain"],
-          "notes" => nil,
-          "notes" => "",
-          "summary" => "Show this endpoint",
-          "nickname" => "GET-simple-show---format-",
-          "httpMethod" => "GET",
-          "parameters" => []
+    expect(JSON.parse(last_response.body)).to eq(
+      'apiVersion' => '0.1',
+      'swaggerVersion' => '1.2',
+      'basePath' => 'http://example.org',
+      'resourcePath' => '/simple',
+      'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+      'apis' => [{
+        'path' => '/simple/show.{format}',
+        'operations' => [{
+          'notes' => '',
+          'summary' => 'Show this endpoint',
+          'nickname' => 'GET-simple-show---format-',
+          'method' => 'GET',
+          'parameters' => [],
+          'type' => 'void'
         }]
       }]
-    }
+    )
   end
 end

data/spec/markdown/kramdown_adapter_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe GrapeSwagger::Markdown::KramdownAdapter do
+
+  context 'initialization' do
+    it 'uses GFM as default input and disable coderay' do
+      adapter = GrapeSwagger::Markdown::KramdownAdapter.new
+
+      expect(adapter.options).to eq(input: 'GFM', enable_coderay: false)
+    end
+
+    it 'overrides default values' do
+      options = { input: 'kramdown', enable_coderay: true }
+
+      adapter = GrapeSwagger::Markdown::KramdownAdapter.new options
+
+      expect(adapter.options).to eq(options)
+    end
+
+    it 'raises an GrapeSwagger::Errors::MarkdownDependencyMissingError if module can not be required' do
+      expect_any_instance_of(Kernel).to receive(:require).with('kramdown').and_raise(LoadError)
+
+      expect { GrapeSwagger::Markdown::KramdownAdapter.new }.to raise_error(GrapeSwagger::Errors::MarkdownDependencyMissingError, 'Missing required dependency: kramdown')
+    end
+  end
+
+  context 'markdown' do
+    it 'marks down with the configured options' do
+      text = '# hello world #'
+      options = { input: 'GFM', enable_coderay: true, auto_ids: false, hard_wrap: true }
+      expect(Kramdown::Document).to receive(:new).with(text, options).and_call_original
+
+      output = GrapeSwagger::Markdown::KramdownAdapter.new(options).markdown(text)
+
+      expect(output).to include('<h1>hello world</h1>')
+    end
+  end
+end

data/spec/markdown/markdown_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe GrapeSwagger::Markdown do
+  context 'initialization' do
+    it 'initializes with an class that respond to markdown' do
+      adapter = GrapeSwagger::Markdown::KramdownAdapter.new
+
+      markdown = GrapeSwagger::Markdown.new adapter
+
+      expect(markdown.adapter).to eq(adapter)
+    end
+
+    it 'raises an exception when the class does not respond to markdown' do
+      expect { GrapeSwagger::Markdown.new(Class.new) }.to raise_error(ArgumentError, 'The configured markdown adapter should implement the method markdown')
+    end
+  end
+
+  context 'as_markdown' do
+    it 'calls markdown on the configured adapter' do
+      text = '# Hello world #'
+      adapter = GrapeSwagger::Markdown::KramdownAdapter.new
+      expect(adapter).to receive(:markdown).with(text)
+
+      GrapeSwagger::Markdown.new(adapter).as_markdown(text)
+    end
+  end
+end

data/spec/markdown/redcarpet_adapter_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+
+describe GrapeSwagger::Markdown::RedcarpetAdapter, unless: RUBY_PLATFORM.eql?('java') do
+
+  context 'initialization' do
+    context 'initialization' do
+      it 'uses fenced_code_blocks, auto_links and rouge as default.' do
+        expect_any_instance_of(GrapeSwagger::Markdown::RedcarpetAdapter).to receive(:new_redcarpet_renderer).with(:rouge).and_call_original
+
+        adapter = GrapeSwagger::Markdown::RedcarpetAdapter.new
+
+        expect(adapter.extension_options).to eq(fenced_code_blocks: true, autolink: true)
+        expect(adapter.render_options).to eq({})
+      end
+
+      it 'initializes with no highlighter.' do
+        expect_any_instance_of(GrapeSwagger::Markdown::RedcarpetAdapter).to receive(:new_redcarpet_renderer).with(:none).and_call_original
+
+        adapter = GrapeSwagger::Markdown::RedcarpetAdapter.new render_options: { highlighter: :none }
+
+        expect(adapter.extension_options).to eq(fenced_code_blocks: true, autolink: true)
+        expect(adapter.render_options).to eq({})
+      end
+
+      it 'overrides default values' do
+        extensions = { fenced_code_blocks: true, autolink: true }
+        render_options = { highlighter: :none, no_links: true }
+
+        adapter = GrapeSwagger::Markdown::RedcarpetAdapter.new extensions: extensions, render_options: render_options
+
+        expect(adapter.extension_options).to eq(extensions)
+        expect(adapter.render_options).to eq(no_links: true)
+      end
+
+      it 'raises an GrapeSwagger::Errors::MarkdownDependencyMissingError if module can not be required.' do
+        expect_any_instance_of(Kernel).to receive(:require).with('redcarpet').and_raise(LoadError)
+
+        expect { GrapeSwagger::Markdown::RedcarpetAdapter.new }.to raise_error(GrapeSwagger::Errors::MarkdownDependencyMissingError, 'Missing required dependency: redcarpet')
+      end
+    end
+
+    context 'markdown' do
+      it 'marks down with the configured options' do
+        text = '# hello world #'
+        extensions = { fenced_code_blocks: true, autolink: true }
+        render_options = { highlighter: :none, no_links: true, highlighter: :none }
+        expect_any_instance_of(Redcarpet::Markdown).to receive(:render).with(text).and_call_original
+
+        output = GrapeSwagger::Markdown::RedcarpetAdapter.new(extensions: extensions, render_options: render_options).markdown(text)
+
+        expect(output).to include('<h1>hello world</h1>')
+      end
+    end
+
+    context 'new_redcarpet_renderer' do
+      it 'returns a rouge syntax highlighter' do
+        adapter = GrapeSwagger::Markdown::RedcarpetAdapter.new
+        renderer = adapter.send(:new_redcarpet_renderer, :rouge)
+
+        expect(renderer).to include(Rouge::Plugins::Redcarpet)
+        expect(renderer.superclass).to be(Redcarpet::Render::HTML)
+      end
+
+      it 'throws an error when rouge syntax highlighter cant be included' do
+        adapter = GrapeSwagger::Markdown::RedcarpetAdapter.new
+
+        expect_any_instance_of(Kernel).to receive(:require).with('rouge').and_raise(LoadError)
+
+        expect { adapter.send(:new_redcarpet_renderer, :rouge) }.to raise_error(GrapeSwagger::Errors::MarkdownDependencyMissingError, 'Missing required dependency: rouge')
+      end
+
+      it 'returns a default syntax highlighter' do
+        adapter = GrapeSwagger::Markdown::RedcarpetAdapter.new
+        renderer = adapter.send(:new_redcarpet_renderer, :none)
+
+        expect(renderer).to include(GrapeSwagger::Markdown::RedcarpetAdapter::RenderWithoutSyntaxHighlighter)
+        expect(renderer.superclass).to be(Redcarpet::Render::HTML)
+      end
+    end
+  end
+end

data/spec/namespaced_api_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe 'namespace' do
+  context 'at root level' do
+    def app
+      Class.new(Grape::API) do
+        namespace :aspace, desc: 'Description for aspace' do
+          get '/'
+        end
+        add_swagger_documentation format: :json
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['apis'][0]
+    end
+
+    it 'shows the namespace description in the json spec' do
+      expect(subject['description']).to eql('Description for aspace')
+    end
+  end
+
+  context 'mounted' do
+    def app
+      namespaced_api = Class.new(Grape::API) do
+        namespace :aspace, desc: 'Description for aspace' do
+          get '/'
+        end
+      end
+
+      Class.new(Grape::API) do
+        mount namespaced_api
+        add_swagger_documentation format: :json
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['apis'][0]
+    end
+
+    it 'shows the namespace description in the json spec' do
+      expect(subject['description']).to eql('Description for aspace')
+    end
+  end
+end

data/spec/non_default_api_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
-describe "options: " do
-  context "overriding the basepath" do
+describe 'options: ' do
+  context 'overriding the basepath' do
     before :all do
 
       class BasePathMountedApi < Grape::API
@@ -12,30 +12,35 @@ describe "options: " do
       end
 
       class SimpleApiWithBasePath < Grape::API
-        NON_DEFAULT_BASE_PATH = "http://www.breakcoregivesmewood.com"
+        NON_DEFAULT_BASE_PATH = 'http://www.breakcoregivesmewood.com'
 
         mount BasePathMountedApi
-        add_swagger_documentation :base_path => NON_DEFAULT_BASE_PATH
+        add_swagger_documentation base_path: NON_DEFAULT_BASE_PATH
       end
 
     end
 
-    def app; SimpleApiWithBasePath end
-
-    it "retrieves the given base-path on /swagger_doc" do
-      get '/swagger_doc.json'
-      JSON.parse(last_response.body)["basePath"].should == SimpleApiWithBasePath::NON_DEFAULT_BASE_PATH
+    def app
+      SimpleApiWithBasePath
     end
 
-    it "retrieves the same given base-path for mounted-api" do
+    subject do
       get '/swagger_doc/something.json'
-      JSON.parse(last_response.body)["basePath"].should == SimpleApiWithBasePath::NON_DEFAULT_BASE_PATH
+      JSON.parse(last_response.body)
+    end
+
+    # it "retrieves the given base-path on /swagger_doc" do
+    #   get '/swagger_doc.json'
+    #   JSON.parse(last_response.body)["basePath"].should == SimpleApiWithBasePath::NON_DEFAULT_BASE_PATH
+    # end
+
+    it 'retrieves the same given base-path for mounted-api' do
+      expect(subject['basePath']).to eq SimpleApiWithBasePath::NON_DEFAULT_BASE_PATH
     end
   end
 
-  context "overriding the basepath with a proc" do
+  context 'overriding the basepath with a proc' do
     before :all do
-
       class ProcBasePathMountedApi < Grape::API
         desc 'This gets something.'
         get '/something' do
@@ -45,26 +50,31 @@ describe "options: " do
 
       class SimpleApiWithProcBasePath < Grape::API
         mount ProcBasePathMountedApi
-        add_swagger_documentation base_path: lambda { |request| "#{request.base_url}/some_value" }
+        add_swagger_documentation base_path: proc { |request| "#{request.base_url}/some_value" }
       end
     end
 
-    def app; SimpleApiWithProcBasePath end
-
-    it "retrieves the given base-path on /swagger_doc" do
-      get '/swagger_doc.json'
-      JSON.parse(last_response.body)["basePath"].should == "http://example.org/some_value"
+    def app
+      SimpleApiWithProcBasePath
     end
 
-    it "retrieves the same given base-path for mounted-api" do
+    subject do
       get '/swagger_doc/something.json'
-      JSON.parse(last_response.body)["basePath"].should == "http://example.org/some_value"
+      JSON.parse(last_response.body)
+    end
+
+    # it "retrieves the given base-path on /swagger_doc" do
+    #   get '/swagger_doc.json'
+    #   JSON.parse(last_response.body)["basePath"].should == "http://example.org/some_value"
+    # end
+
+    it 'retrieves the same given base-path for mounted-api' do
+      expect(subject['basePath']).to eq 'http://example.org/some_value'
     end
   end
 
-  context "relative base_path" do
+  context 'relative base_path' do
     before :all do
-
       class RelativeBasePathMountedApi < Grape::API
         desc 'This gets something.'
         get '/something' do
@@ -74,26 +84,32 @@ describe "options: " do
 
       class SimpleApiWithRelativeBasePath < Grape::API
         mount RelativeBasePathMountedApi
-        add_swagger_documentation base_path: "/some_value"
+        add_swagger_documentation base_path: '/some_value'
       end
     end
 
-    def app; SimpleApiWithRelativeBasePath end
+    def app
+      SimpleApiWithRelativeBasePath
+    end
 
-    it "retrieves the given base-path on /swagger_doc" do
-      get '/swagger_doc.json'
-      JSON.parse(last_response.body)["basePath"].should == "http://example.org/some_value"
+    subject do
+      get '/swagger_doc/something.json'
+      JSON.parse(last_response.body)
     end
 
-    it "retrieves the same given base-path for mounted-api" do
+    # it "retrieves the given base-path on /swagger_doc" do
+    #   get '/swagger_doc.json'
+    #   JSON.parse(last_response.body)["basePath"].should == "http://example.org/some_value"
+    # end
+
+    it 'retrieves the same given base-path for mounted-api' do
       get '/swagger_doc/something.json'
-      JSON.parse(last_response.body)["basePath"].should == "http://example.org/some_value"
+      expect(subject['basePath']).to eq 'http://example.org/some_value'
     end
   end
 
-  context "overriding the version" do
+  context 'overriding the version' do
     before :all do
-
       class ApiVersionMountedApi < Grape::API
         desc 'This gets something.'
         get '/something' do
@@ -102,29 +118,30 @@ describe "options: " do
       end
 
       class SimpleApiWithApiVersion < Grape::API
-        API_VERSION = "101"
+        API_VERSION = '101'
 
         mount ApiVersionMountedApi
-        add_swagger_documentation :api_version => API_VERSION
+        add_swagger_documentation api_version: API_VERSION
       end
     end
 
-    def app; SimpleApiWithApiVersion end
+    def app
+      SimpleApiWithApiVersion
+    end
 
-    it "retrieves the api version on /swagger_doc" do
+    it 'retrieves the api version on /swagger_doc' do
       get '/swagger_doc.json'
-      JSON.parse(last_response.body)["apiVersion"].should == SimpleApiWithApiVersion::API_VERSION
+      expect(JSON.parse(last_response.body)['apiVersion']).to eq SimpleApiWithApiVersion::API_VERSION
     end
 
-    it "retrieves the same api version for mounted-api" do
+    it 'retrieves the same api version for mounted-api' do
       get '/swagger_doc/something.json'
-      JSON.parse(last_response.body)["apiVersion"].should == SimpleApiWithApiVersion::API_VERSION
+      expect(JSON.parse(last_response.body)['apiVersion']).to eq SimpleApiWithApiVersion::API_VERSION
     end
   end
 
-  context "mounting in a versioned api" do
+  context 'mounting in a versioned api' do
     before :all do
-
       class SimpleApiToMountInVersionedApi < Grape::API
         desc 'This gets something.'
         get '/something' do
@@ -133,58 +150,57 @@ describe "options: " do
       end
 
       class SimpleApiWithVersionInPath < Grape::API
-        version 'v1', :using => :path
+        version 'v1', using: :path
 
         mount SimpleApiToMountInVersionedApi
         add_swagger_documentation
       end
     end
 
-    def app; SimpleApiWithVersionInPath end
+    def app
+      SimpleApiWithVersionInPath
+    end
 
-    it "gets the documentation on a versioned path /v1/swagger_doc" do
+    it 'gets the documentation on a versioned path /v1/swagger_doc' do
       get '/v1/swagger_doc.json'
-
-      JSON.parse(last_response.body).should == {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "info" => {},
-        "produces" => ["application/xml", "application/json", "text/plain"],
-        "operations" => [],
-        "apis" => [
-          { "path" => "/v1/swagger_doc/something.{format}" },
-          { "path" => "/v1/swagger_doc/swagger_doc.{format}" }
+      expect(last_response.status).to eq 200
+      expect(JSON.parse(last_response.body)).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'info' => {},
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [
+          { 'path' => '/something.{format}', 'description' => 'Operations about somethings' },
+          { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
         ]
-      }
+      )
     end
 
-    it "gets the resource specific documentation on a versioned path /v1/swagger_doc/something" do
+    it 'gets the resource specific documentation on a versioned path /v1/swagger_doc/something' do
       get '/v1/swagger_doc/something.json'
-      last_response.status.should == 200
-      JSON.parse(last_response.body).should == {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "resourcePath" => "",
-        "apis" => [{
-          "path" => "/0.1/something.{format}",
-          "operations" => [{
-            "produces" => ["application/xml", "application/json", "text/plain"],
-            "notes" => nil,
-            "notes" => "",
-            "summary" => "This gets something.",
-            "nickname" => "GET--version-something---format-",
-            "httpMethod" => "GET",
-            "parameters" => []
+      expect(last_response.status).to eq 200
+      expect(JSON.parse(last_response.body)).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'basePath' => 'http://example.org',
+        'resourcePath' => '/something',
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [{
+          'path' => '/0.1/something.{format}',
+          'operations' => [{
+            'notes' => '',
+            'summary' => 'This gets something.',
+            'nickname' => 'GET--version-something---format-',
+            'method' => 'GET',
+            'parameters' => [],
+            'type' => 'void'
           }]
         }]
-      }
+      )
     end
-
   end
 
-  context "overriding hiding the documentation paths" do
+  context 'overriding hiding the documentation paths' do
     before :all do
       class HideDocumentationPathMountedApi < Grape::API
         desc 'This gets something.'
@@ -195,29 +211,33 @@ describe "options: " do
 
       class SimpleApiWithHiddenDocumentation < Grape::API
         mount HideDocumentationPathMountedApi
-        add_swagger_documentation :hide_documentation_path => true
+        add_swagger_documentation hide_documentation_path: true
       end
     end
 
-    def app; SimpleApiWithHiddenDocumentation end
+    def app
+      SimpleApiWithHiddenDocumentation
+    end
 
-    it "it doesn't show the documentation path on /swagger_doc" do
+    subject do
       get '/swagger_doc.json'
-      JSON.parse(last_response.body).should == {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "info" => {},
-        "produces" => ["application/xml", "application/json", "text/plain"],
-        "operations" => [],
-        "apis" => [
-          { "path" => "/swagger_doc/something.{format}" }
+      JSON.parse(last_response.body)
+    end
+
+    it "it doesn't show the documentation path on /swagger_doc" do
+      expect(subject).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'info' => {},
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [
+          { 'path' => '/something.{format}', 'description' => 'Operations about somethings' }
         ]
-      }
+      )
     end
   end
 
-  context "overriding hiding the documentation paths in prefixed API" do
+  context 'overriding hiding the documentation paths in prefixed API' do
     before :all do
       class HideDocumentationPathPrefixedMountedApi < Grape::API
         desc 'This gets something.'
@@ -227,40 +247,46 @@ describe "options: " do
       end
 
       class PrefixedApiWithHiddenDocumentation < Grape::API
-        prefix "abc"
+        prefix 'abc'
         mount HideDocumentationPathPrefixedMountedApi
-        add_swagger_documentation :hide_documentation_path => true
+        add_swagger_documentation hide_documentation_path: true
       end
 
     end
 
-    def app; PrefixedApiWithHiddenDocumentation end
+    def app
+      PrefixedApiWithHiddenDocumentation
+    end
 
-    it "it doesn't show the documentation path on /abc/swagger_doc/something.json" do
+    subject do
       get '/abc/swagger_doc/something.json'
-      JSON.parse(last_response.body).should == {
-        "apiVersion"=>"0.1",
-        "swaggerVersion"=>"1.2",
-        "basePath"=>"http://example.org",
-        "resourcePath"=>"",
-        "apis"=> [{
-          "path"=>"/abc/something.{format}",
-          "operations"=> [{
-            "produces" => ["application/xml", "application/json", "text/plain"],
-            "notes"=>nil,
-            "notes"=>"",
-            "summary"=>"This gets something.",
-            "nickname"=>"GET-abc-something---format-",
-            "httpMethod"=>"GET",
-            "parameters"=>[]
+      JSON.parse(last_response.body)
+    end
+
+    it "it doesn't show the documentation path on /abc/swagger_doc/something.json" do
+      expect(subject).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'basePath' => 'http://example.org',
+        'resourcePath' => '/something',
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [{
+          'path' => '/abc/something.{format}',
+          'operations' => [{
+            'notes' => '',
+            'summary' => 'This gets something.',
+            'nickname' => 'GET-abc-something---format-',
+            'method' => 'GET',
+            'parameters' => [],
+            'type' => 'void'
           }]
         }]
-      }
+      )
     end
 
   end
 
-  context "overriding hiding the documentation paths in prefixed and versioned API" do
+  context 'overriding hiding the documentation paths in prefixed and versioned API' do
     before :all do
       class HideDocumentationPathMountedApi2 < Grape::API
         desc 'This gets something.'
@@ -270,43 +296,49 @@ describe "options: " do
       end
 
       class PrefixedAndVersionedApiWithHiddenDocumentation < Grape::API
-        prefix "abc"
-        version 'v20', :using => :path
+        prefix 'abc'
+        version 'v20', using: :path
 
         mount HideDocumentationPathMountedApi2
 
-        add_swagger_documentation :hide_documentation_path => true, :api_version => self.version
+        add_swagger_documentation hide_documentation_path: true, api_version: version
       end
     end
 
-    def app; PrefixedAndVersionedApiWithHiddenDocumentation end
+    def app
+      PrefixedAndVersionedApiWithHiddenDocumentation
+    end
 
-    it "it doesn't show the documentation path on /abc/v1/swagger_doc/something.json" do
+    subject do
       get '/abc/v20/swagger_doc/something.json'
+      JSON.parse(last_response.body)
+    end
 
-      JSON.parse(last_response.body).should == {
-        "apiVersion"=>"v20",
-        "swaggerVersion"=>"1.2",
-        "basePath"=>"http://example.org",
-        "resourcePath"=>"",
-        "apis"=>[{
-          "path"=>"/abc/v20/something.{format}",
-          "operations"=>[{
-            "produces" => ["application/xml", "application/json", "text/plain"],
-            "notes"=>nil,
-            "notes"=>"",
-            "summary"=>"This gets something.",
-            "nickname"=>"GET-abc--version-something---format-",
-            "httpMethod"=>"GET",
-            "parameters"=>[]
+    it "it doesn't show the documentation path on /abc/v1/swagger_doc/something.json" do
+      expect(subject).to eq(
+        'apiVersion' => 'v20',
+        'swaggerVersion' => '1.2',
+        'basePath' => 'http://example.org',
+        'resourcePath' => '/something',
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [{
+          'path' => '/abc/v20/something.{format}',
+          'operations' => [{
+            'notes' => nil,
+            'notes' => '',
+            'summary' => 'This gets something.',
+            'nickname' => 'GET-abc--version-something---format-',
+            'method' => 'GET',
+            'parameters' => [],
+            'type' => 'void'
           }]
         }]
-      }
+      )
     end
 
   end
 
-  context "overriding the mount-path" do
+  context 'overriding the mount-path' do
     before :all do
       class DifferentMountMountedApi < Grape::API
         desc 'This gets something.'
@@ -316,42 +348,41 @@ describe "options: " do
       end
 
       class SimpleApiWithDifferentMount < Grape::API
-        MOUNT_PATH = "/api_doc"
+        MOUNT_PATH = '/api_doc'
 
         mount DifferentMountMountedApi
-        add_swagger_documentation :mount_path => MOUNT_PATH
+        add_swagger_documentation mount_path: MOUNT_PATH
       end
     end
 
-    def app; SimpleApiWithDifferentMount end
-
-
-    it "retrieves the given base-path on /api_doc" do
-      get '/api_doc.json'
-        JSON.parse(last_response.body)["apis"].each do |api|
-        api["path"].should start_with SimpleApiWithDifferentMount::MOUNT_PATH
-      end
+    def app
+      SimpleApiWithDifferentMount
     end
 
-    it "retrieves the same given base-path for mounted-api" do
+    # it "retrieves the given base-path on /api_doc" do
+    #   get '/api_doc.json'
+    #     JSON.parse(last_response.body)["apis"].each do |api|
+    #     api["path"].should start_with SimpleApiWithDifferentMount::MOUNT_PATH
+    #   end
+    # end
+
+    it 'retrieves the same given base-path for mounted-api' do
       get '/api_doc/something.json'
-      JSON.parse(last_response.body)["apis"].each do |api|
-        api["path"].should_not start_with SimpleApiWithDifferentMount::MOUNT_PATH
+      JSON.parse(last_response.body)['apis'].each do |api|
+        expect(api['path']).to_not start_with SimpleApiWithDifferentMount::MOUNT_PATH
       end
     end
 
-    it "does not respond to swagger_doc" do
+    it 'does not respond to swagger_doc' do
       get '/swagger_doc.json'
-      last_response.status.should be == 404
+      expect(last_response.status).to eq 404
     end
   end
 
-  context "overriding the markdown" do
+  context 'overriding the markdown' do
     before :all do
       class MarkDownMountedApi < Grape::API
-        desc 'This gets something.', {
-          :notes => '_test_'
-        }
+        desc 'This gets something.', notes: '_test_'
         get '/something' do
           { bla: 'something' }
         end
@@ -359,35 +390,54 @@ describe "options: " do
 
       class SimpleApiWithMarkdown < Grape::API
         mount MarkDownMountedApi
-        add_swagger_documentation :markdown => true
+        add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter.new, info: { description: '_test_' }
+      end
+    end
+
+    subject do
+      Class.new(Grape::API) do
+        mount MarkDownMountedApi
       end
     end
 
-    def app; SimpleApiWithMarkdown end
+    def app
+      SimpleApiWithMarkdown
+    end
 
-    it "parses markdown for a mounted-api" do
-      get '/swagger_doc/something.json'
-      JSON.parse(last_response.body).should ==  {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "resourcePath" => "",
-        "apis" => [{
-          "path" => "/something.{format}",
-          "operations" => [{
-            "produces" => ["application/xml", "application/json", "text/plain"],
-            "notes" => "<p><em>test</em></p>\n",
-            "summary" => "This gets something.",
-            "nickname" => "GET-something---format-",
-            "httpMethod" => "GET",
-            "parameters" => []
-          }]
-        }]
-      }
+    context 'with instance' do
+      before do
+        subject.add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter.new, info: { description: '_test_' }
+      end
+
+      it 'parses markdown for a mounted-api' do
+        get '/swagger_doc/something.json'
+        expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
+      end
+
+      it 'parses markdown for swagger info' do
+        get '/swagger_doc.json'
+        expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
+      end
+    end
+
+    context 'with class' do
+      before do
+        subject.add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter, info: { description: '_test_' }
+      end
+
+      it 'parses markdown for a mounted-api' do
+        get '/swagger_doc/something.json'
+        expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
+      end
+
+      it 'parses markdown for swagger info' do
+        get '/swagger_doc.json'
+        expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
+      end
     end
   end
 
-  context "prefixed and versioned API" do
+  context 'prefixed and versioned API' do
     before :all do
       class VersionedMountedApi < Grape::API
         prefix 'api'
@@ -401,22 +451,24 @@ describe "options: " do
 
       class SimpleApiWithVersion < Grape::API
         mount VersionedMountedApi
-        add_swagger_documentation :api_version => "v1"
+        add_swagger_documentation api_version: 'v1'
       end
     end
 
-    def app; SimpleApiWithVersion end
+    def app
+      SimpleApiWithVersion
+    end
 
-    it "parses version and places it in the path" do
+    it 'parses version and places it in the path' do
       get '/swagger_doc/something.json'
 
-      JSON.parse(last_response.body)["apis"].each do |api|
-        api["path"].should start_with "/api/v1/"
+      JSON.parse(last_response.body)['apis'].each do |api|
+        expect(api['path']).to start_with '/api/v1/'
       end
     end
   end
 
-  context "protected API" do
+  context 'protected API' do
     before :all do
       class ProtectedApi < Grape::API
         desc 'This gets something.'
@@ -426,25 +478,27 @@ describe "options: " do
       end
 
       class SimpleApiWithProtection < Grape::API
-        mount ProtectedApi
+        mount ::ProtectedApi
         add_swagger_documentation
       end
     end
 
-    def app; SimpleApiWithProtection; end
-
-    it "uses https schema in mount point" do
-      get '/swagger_doc.json', {}, 'rack.url_scheme' => 'https'
-      JSON.parse(last_response.body)["basePath"].should == "https://example.org:80"
+    def app
+      SimpleApiWithProtection
     end
 
-    it "uses https schema in endpoint doc" do
+    # it "uses https schema in mount point" do
+    #   get '/swagger_doc.json', {}, 'rack.url_scheme' => 'https'
+    #   JSON.parse(last_response.body)["basePath"].should == "https://example.org:80"
+    # end
+
+    it 'uses https schema in endpoint doc' do
       get '/swagger_doc/something.json', {}, 'rack.url_scheme' => 'https'
-      JSON.parse(last_response.body)["basePath"].should == "https://example.org:80"
+      expect(JSON.parse(last_response.body)['basePath']).to eq 'https://example.org:80'
     end
   end
 
-  context ":hide_format" do
+  context ':hide_format' do
     before :all do
       class HidePathsApi < Grape::API
         desc 'This gets something.'
@@ -455,21 +509,23 @@ describe "options: " do
 
       class SimpleApiWithHiddenPaths < Grape::API
         mount ProtectedApi
-        add_swagger_documentation :hide_format => true
+        add_swagger_documentation hide_format: true
       end
     end
 
-    def app; SimpleApiWithHiddenPaths; end
+    def app
+      SimpleApiWithHiddenPaths
+    end
 
-    it "has no formats" do
+    it 'has no formats' do
       get '/swagger_doc/something.json'
-      JSON.parse(last_response.body)["apis"].each do |api|
-        api["path"].should_not end_with ".{format}"
+      JSON.parse(last_response.body)['apis'].each do |api|
+        expect(api['path']).to_not end_with '.{format}'
       end
     end
   end
 
-  context "multiple documentations" do
+  context 'multiple documentations' do
     before :all do
       class FirstApi < Grape::API
         desc 'This is the first API'
@@ -495,40 +551,38 @@ describe "options: " do
       end
     end
 
-    def app; SimpleApiWithMultipleMountedDocumentations; end
+    def app
+      SimpleApiWithMultipleMountedDocumentations
+    end
 
-    it "retrieves the first swagger-documentation on /first/swagger_doc" do
+    it 'retrieves the first swagger-documentation on /first/swagger_doc' do
       get '/first/swagger_doc.json'
-      JSON.parse(last_response.body).should == {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "info" => {},
-        "produces" => ["application/xml", "application/json", "text/plain"],
-        "operations" => [],
-        "apis" => [
-          { "path" => "/first/swagger_doc/first.{format}" }
+      expect(JSON.parse(last_response.body)).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'info' => {},
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [
+          { 'path' => '/first.{format}', 'description' => 'Operations about firsts' }
         ]
-      }
+      )
     end
 
-    it "retrieves the second swagger-documentation on /second/swagger_doc" do
+    it 'retrieves the second swagger-documentation on /second/swagger_doc' do
       get '/second/swagger_doc.json'
-      JSON.parse(last_response.body).should == {
-        "apiVersion" => "0.1",
-        "swaggerVersion" => "1.2",
-        "basePath" => "http://example.org",
-        "info" => {},
-        "produces" => ["application/xml", "application/json", "text/plain"],
-        "operations" => [],
-        "apis" => [
-          { "path" => "/second/swagger_doc/second.{format}" }
+      expect(JSON.parse(last_response.body)).to eq(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'info' => {},
+        'produces' => ['application/xml', 'application/json', 'application/vnd.api+json', 'text/plain'],
+        'apis' => [
+          { 'path' => '/second.{format}', 'description' => 'Operations about seconds' }
         ]
-      }
+      )
     end
   end
 
-  context ":formatting" do
+  context ':formatting' do
     before :all do
       class JSONDefaultFormatAPI < Grape::API
         desc 'This gets something.'
@@ -543,13 +597,109 @@ describe "options: " do
       end
     end
 
-    def app; SimpleJSONFormattedAPI; end
+    def app
+      SimpleJSONFormattedAPI
+    end
 
-    it "defaults to JSON format when none is specified" do
+    subject do
       get '/swagger_doc/something'
+      last_response
+    end
+
+    it 'defaults to JSON format when none is specified' do
+      get '/swagger_doc/something'
+      expect(subject.headers['Content-Type']).to eq 'application/json'
+      expect(-> { JSON.parse(subject.body) }).to_not raise_error
+    end
+  end
+
+  context 'documented namespace description' do
+    before :all do
+      class NestedNamespaceWithDescAPI < Grape::API
+        namespace :nestedspace, desc: 'Description for nested space' do
+          desc 'Nested get'
+          get '/somethingelse' do
+            { foo: 'bar' }
+          end
+        end
+      end
+
+      class NamespaceWithDescAPI < Grape::API
+        namespace :aspace, desc: 'Description for aspace' do
+          desc 'This gets something.'
+          get '/something' do
+            { bla: 'something' }
+          end
+        end
+
+        mount NestedNamespaceWithDescAPI
+
+        add_swagger_documentation format: :json
+      end
+      get '/swagger_doc'
+    end
+
+    def app
+      NamespaceWithDescAPI
+    end
 
-      lambda{ JSON.parse(last_response.body) }.should_not raise_error
+    subject do
+      JSON.parse(last_response.body)['apis']
     end
 
+    it 'shows the namespace description in the json spec' do
+      expect(subject[0]['description']).to eql('Description for aspace')
+    end
+
+    it 'shows the nested namespace description in the json spec' do
+      expect(subject[1]['description']).to eql('Description for nested space')
+    end
+  end
+
+  context 'override nickname' do
+    before :all do
+      class NicknameAPI < Grape::API
+        desc 'This gets something.', nickname: 'getSomething'
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation
+      end
+    end
+
+    def app
+      NicknameAPI
+    end
+
+    it 'documents the user-specified nickname' do
+      get '/swagger_doc/something.json'
+      ret = JSON.parse(last_response.body)
+      expect(ret['apis'][0]['operations'][0]['nickname']).to eq 'getSomething'
+    end
+  end
+
+  context 'invalid name' do
+    subject do
+      Class.new(Grape::API) do
+        get 'hidden', hidden: true
+        add_swagger_documentation
+      end
+    end
+
+    def app
+      subject
+    end
+
+    it 'returns a 404 for an non-existent route' do
+      get '/swagger_doc/invalid.json'
+      expect(last_response.status).to eq 404
+      expect(JSON.parse(last_response.body)).to eq('error' => 'Not Found')
+    end
+
+    it 'returns a 404 for a hidden route' do
+      get '/swagger_doc/hidden.json'
+      expect(last_response.status).to eq 404
+      expect(JSON.parse(last_response.body)).to eq('error' => 'Not Found')
+    end
   end
 end