grape-swagger 0.11.0 → 0.20.0

data/spec/support/namespace_tags.rb

@@ -0,0 +1,73 @@
+RSpec.shared_context "namespace example" do
+  before :all do
+    module TheApi
+
+      class CustomType; end
+
+      class NamespaceApi < Grape::API
+
+        namespace :hudson do
+          desc 'Document root'
+          get '/' do
+          end
+        end
+
+        namespace :colorado do
+          desc 'This gets something.',
+            notes: '_test_'
+
+          get '/simple' do
+            { bla: 'something' }
+          end
+        end
+
+        namespace :colorado do
+          desc 'This gets something for URL using - separator.',
+            notes: '_test_'
+
+          get '/simple-test' do
+            { bla: 'something' }
+          end
+        end
+
+        namespace :thames do
+          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
+        end
+
+        namespace :niles do
+          desc 'this takes an array of parameters',
+            params: {
+              'items[]' => { description: 'array of items', is_array: true }
+            }
+
+          post '/items' do
+            {}
+          end
+        end
+
+        namespace :niles do
+          desc 'this uses a custom parameter',
+            params: {
+              'custom' => { type: CustomType, description: 'array of items', is_array: true }
+            }
+
+          get '/custom' do
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/spec/support/the_api_entities.rb

@@ -0,0 +1,52 @@
+RSpec.shared_context "the api entities" do
+  before :all do
+    module TheApi
+      module Entities
+        class ApiError < Grape::Entity
+          expose :code, documentation: { type: Integer }
+          expose :message, documentation: { type: String }
+        end
+
+        class SecondApiError < Grape::Entity
+          expose :code, documentation: { type: Integer }
+          expose :severity, documentation: { type: String }
+          expose :message, documentation: { type: String }
+        end
+
+        class ResponseItem < Grape::Entity
+          expose :id, documentation: { type: Integer }
+          expose :name, documentation: { type: String }
+        end
+
+        class OtherItem < Grape::Entity
+          expose :key, documentation: { type: Integer }
+          expose :symbol, documentation: { type: String }
+        end
+
+        class UseResponse < Grape::Entity
+          expose :description, documentation: { type: String }
+          expose :items, as: '$responses', using: Entities::ResponseItem, documentation: { is_array: true }
+        end
+
+        class UseItemResponseAsType < Grape::Entity
+          expose :description, documentation: { type: String }
+          expose :responses, documentation: { type: Entities::ResponseItem, is_array: false }
+        end
+
+        class UseAddress < Grape::Entity
+          expose :street, documentation: { type: String, desc: 'street' }
+          expose :postcode, documentation: { type: String, desc: 'postcode' }
+          expose :city, documentation: { type: String, desc: 'city' }
+          expose :country, documentation: { type: String, desc: 'country' }
+        end
+
+        class UseNestedWithAddress < Grape::Entity
+          expose :name, documentation: { type: String }
+          expose :address, using: Entities::UseAddress
+        end
+      end
+    end
+  end
+
+
+end

data/spec/support/the_paths_definitions.rb

@@ -0,0 +1,94 @@
+RSpec.shared_context "the api paths/defs" do
+  let(:paths) {{
+    "/in_body" => {
+      post: {
+        produces: ["application/json"],
+        consumes: ["application/json"],
+        parameters: [
+          {in: "body", name: "in_body_1", description: "in_body_1", type: "integer", format: "int32", required: true},
+          {in: "body", name: "in_body_2", description: "in_body_2", type: "string", required: false},
+          {in: "body", name: "in_body_3", description: "in_body_3", type: "string", required: false}
+        ],
+        responses: {201 => {description: "post in body /wo entity", schema: {"$ref" => "#/definitions/InBody"}}},
+        tags: ["in_body"],
+        operationId: "postInBody"
+      },
+      get: {
+        produces: ["application/json"],
+        responses: {200 => {description: "get in path /wo entity", schema: {"$ref" => "#/definitions/InBody"}}},
+        tags: ["in_body"],
+        operationId: "getInBody"
+      }
+    },
+    "/in_body/{key}" => {
+      put: {
+        produces: ["application/json"],
+        consumes: ["application/json"],
+        parameters: [
+          {in: "path", name: "key", description: nil, type: "integer", format: "int32", required: true},
+          {in: "body", name: "in_body_1", description: "in_body_1", type: "integer", format: "int32", required: true},
+          {in: "body", name: "in_body_2", description: "in_body_2", type: "string", required: false},
+          {in: "body", name: "in_body_3", description: "in_body_3", type: "string", required: false}
+        ],
+        responses: {200 => {description: "put in body /wo entity", schema: {"$ref" => "#/definitions/InBody"}}},
+        tags: ["in_body"],
+        operationId: "putInBodyKey"
+      },
+      get: {
+        produces: ["application/json"],
+        parameters: [
+          {in: "path", name: "key", description: nil, type: "integer", format: "int32", required: true}
+        ],
+        responses: {200 => {description: "get in path /wo entity", schema: {"$ref" => "#/definitions/InBody"}}},
+        tags: ["in_body"],
+        operationId: "getInBodyKey"
+    }}
+  }}
+
+  let(:found_path) {{
+    post: {
+      produces: ["application/json"],
+      consumes: ["application/json"],
+      parameters: [
+        {in: "body", name: "in_body_1", description: "in_body_1", type: "integer", format: "int32", required: true},
+        {in: "body", name: "in_body_2", description: "in_body_2", type: "string", required: false},
+        {in: "body", name: "in_body_3", description: "in_body_3", type: "string", required: false}
+      ],
+      responses: {201 =>  {description: "post in body /wo entity", schema: {"$ref"=>"#/definitions/InBody"}}},
+      tags: ["in_body"],
+      operationId: "postInBody"
+  }}}
+
+  let(:definitions) {{
+    "InBody" => {
+      type: "object",
+      properties: {
+        in_body_1: {type: "integer", format: "int32"},
+        in_body_2: {type: "string"},
+        in_body_3: {type: "string"},
+        key: {type: "integer", format: "int32"}
+  }}}}
+
+  let(:expected_post_defs) {{
+    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]
+  }}
+
+  let(:expected_put_defs) {{
+    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"},
+      key: {type: "integer", format: "int32", readOnly: true}
+    },
+    :required=>[:in_body_1]
+  }}
+
+  let(:expected_path) {[]}
+end

data/spec/swagger_v2/api_swagger_v2_definitions-models_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe 'definitions/models' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class ModelApi < Grape::API
+        format :json
+
+        add_swagger_documentation models: [
+          TheApi::Entities::UseResponse,
+          TheApi::Entities::ApiError
+        ]
+      end
+    end
+  end
+
+  def app
+    TheApi::ModelApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject).to include 'definitions'
+    expect(subject['definitions']).to include 'ResponseItem', 'UseResponse', 'ApiError'
+  end
+end

data/spec/swagger_v2/api_swagger_v2_detail_spec.rb

@@ -0,0 +1,151 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+def details
+<<-DETAILS
+# Burgers in Heaven
+
+> A burger doesn't come for free
+
+If you want to reserve a burger in heaven, you have to do
+some crazy stuff on earth.
+
+```
+def do_good
+puts 'help people'
+end
+```
+
+* _Will go to Heaven:_ Probably
+* _Will go to Hell:_ Probably not
+DETAILS
+end
+
+describe 'details' do
+  describe "take deatils as it is" do
+    include_context "the api entities"
+
+    before :all do
+      module TheApi
+        class DetailApi < Grape::API
+          format :json
+
+          desc 'This returns something',
+            detail: 'detailed description of the route',
+            entity: Entities::UseResponse,
+            failure: [{code: 400, model: Entities::ApiError}]
+          get '/use_detail' do
+            { "declared_params" => declared(params) }
+          end
+
+          desc 'This returns something' do
+            detail 'detailed description of the route inside the `desc` block'
+            entity Entities::UseResponse
+            failure [{code: 400, model: Entities::ApiError}]
+          end
+          get '/use_detail_block' do
+            { "declared_params" => declared(params) }
+          end
+
+          add_swagger_documentation
+        end
+      end
+    end
+
+    def app
+      TheApi::DetailApi
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_detail']['get']).to include('description')
+      expect(subject['paths']['/use_detail']['get']['description']).to eql "This returns something\n detailed description of the route"
+    end
+
+    specify do
+      expect(subject['paths']['/use_detail_block']['get']).to include('description')
+      expect(subject['paths']['/use_detail_block']['get']['description']).to eql "This returns something\n detailed description of the route inside the `desc` block"
+    end
+  end
+
+  describe 'details, convert markdown with kramdown' do
+    include_context "the api entities"
+
+    before :all do
+      module TheApi
+        class GfmDetailApi < Grape::API
+          format :json
+
+          desc 'This returns something',
+            detail: details,
+            entity: Entities::UseResponse,
+            failure: [{code: 400, model: Entities::ApiError}]
+          get '/use_gfm_detail' do
+            { "declared_params" => declared(params) }
+          end
+
+          add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter.new
+        end
+      end
+    end
+
+    def app
+      TheApi::GfmDetailApi
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_gfm_detail']['get']).to include('description')
+      expect(subject['paths']['/use_gfm_detail']['get']['description']).to eql(
+        "<h1 id=\"this-returns-something\">This returns something</h1>\n<p># Burgers in Heaven</p>\n\n<blockquote>\n  <p>A burger doesn’t come for free</p>\n</blockquote>\n\n<p>If you want to reserve a burger in heaven, you have to do<br />\nsome crazy stuff on earth.</p>\n\n<pre><code>def do_good\nputs 'help people'\nend\n</code></pre>\n\n<ul>\n  <li><em>Will go to Heaven:</em> Probably</li>\n  <li><em>Will go to Hell:</em> Probably not</li>\n</ul>"
+      )
+    end
+  end
+
+  describe 'details, convert markdown with redcarpet', unless: RUBY_PLATFORM.eql?('java') do
+    include_context "the api entities"
+
+    before :all do
+      module TheApi
+        class GfmRcDetailApi < Grape::API
+          format :json
+
+          desc 'This returns something',
+            detail: details,
+            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']).to include('description')
+      expect(subject['paths']['/use_gfm_rc_detail']['get']['description']).to eql(
+        "<h1>This returns something</h1>\n\n<p># Burgers in Heaven</p>\n\n<blockquote>\n<p>A burger doesn&#39;t come for free</p>\n</blockquote>\n\n<p>If you want to reserve a burger in heaven, you have to do\nsome crazy stuff on earth.</p>\n<pre class=\"highlight plaintext\"><code>def do_good\nputs 'help people'\nend\n</code></pre>\n\n<ul>\n<li><em>Will go to Heaven:</em> Probably</li>\n<li><em>Will go to Hell:</em> Probably not</li>\n</ul>"
+      )
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_extensions_spec.rb

@@ -0,0 +1,109 @@
+require 'spec_helper'
+
+describe 'extension' do
+  include_context "the api entities"
+
+  before :all do
+    module TheApi
+      class ExtensionsApi < Grape::API
+        format :json
+
+        route_setting :x_path, { some: 'stuff' }
+
+        desc 'This returns something with extension on path level',
+          params: Entities::UseResponse.documentation,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        get '/path_extension' do
+          { "declared_params" => declared(params) }
+        end
+
+        desc 'This returns something with extension on verb level',
+          params: Entities::UseResponse.documentation,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}],
+          x: { some: 'stuff' }
+        params do
+          requires :id, type: Integer
+        end
+        get '/verb_extension' do
+          { "declared_params" => declared(params) }
+        end
+
+        route_setting :x_def, { for: 200, some: 'stuff' }
+
+        desc 'This returns something with extension on definition level',
+          params: Entities::ResponseItem.documentation,
+          success: Entities::ResponseItem,
+          failure: [{code: 400, message: 'NotFound', model: Entities::ApiError}]
+        get '/definitions_extension' do
+          { "declared_params" => declared(params) }
+        end
+
+        route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }]
+
+        desc 'This returns something with extension on definition level',
+          success: Entities::OtherItem,
+          failure: [{code: 422, message: 'NotFound', model: Entities::SecondApiError}]
+        get '/multiple_definitions_extension' do
+          { "declared_params" => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ExtensionsApi
+  end
+
+  describe "extension on path level" do
+    subject do
+      get '/swagger_doc/path_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/path_extension']).to include 'x-some'
+      expect(subject['paths']['/path_extension']['x-some']).to eql 'stuff'
+    end
+  end
+
+  describe "extension on verb level" do
+    subject do
+      get '/swagger_doc/verb_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/verb_extension']['get']).to include 'x-some'
+      expect(subject['paths']['/verb_extension']['get']['x-some']).to eql 'stuff'
+    end
+  end
+
+  describe "extension on definition level" do
+    subject do
+      get '/swagger_doc/definitions_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['definitions']['ResponseItem']).to include 'x-some'
+      expect(subject['definitions']['ResponseItem']['x-some']).to eql 'stuff'
+      expect(subject['definitions']['ApiError']).not_to include 'x-some'
+    end
+  end
+
+  describe "extension on definition level" do
+    subject do
+      get '/swagger_doc/multiple_definitions_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['definitions']['OtherItem']).to include 'x-some'
+      expect(subject['definitions']['OtherItem']['x-some']).to eql 'stuff'
+      expect(subject['definitions']['SecondApiError']).to include 'x-other'
+      expect(subject['definitions']['SecondApiError']['x-other']).to eql 'stuff'
+    end
+  end
+end