grape-swagger 0.7.2 → 0.8.0

data/lib/grape-swagger/errors.rb

@@ -0,0 +1,9 @@
+module GrapeSwagger
+  module Errors
+    class MarkdownDependencyMissingError < StandardError
+      def initialize(missing_gem)
+        super("Missing required dependency: #{missing_gem}")
+      end
+    end
+  end
+end

data/lib/grape-swagger/markdown.rb

@@ -0,0 +1,23 @@
+module GrapeSwagger
+  class Markdown
+    attr_reader :adapter
+
+    ###
+    # Initializes the markdown class with an adapter.
+    # The adapter needs to implement the method markdown which will be called by this interface class.
+    # The adapters are responsible of loading the required markdown dependencies and throw errors.
+    ###
+    def initialize(adapter)
+      adapter = adapter.new if adapter.is_a?(Class)
+      fail(ArgumentError, "The configured markdown adapter should implement the method #{ :markdown }") unless adapter.respond_to? :markdown
+      @adapter = adapter
+    end
+
+    ###
+    # Calls markdown to the configured adapter.
+    ###
+    def as_markdown(text)
+      @adapter.markdown(text)
+    end
+  end
+end

data/lib/grape-swagger/markdown/kramdown_adapter.rb

@@ -0,0 +1,37 @@
+module GrapeSwagger
+  class Markdown
+    class KramdownAdapter
+      attr_reader :options
+
+      ###
+      # Initializes the kramdown adapter with options.
+      # See kramdown documentation what options can be passed.
+      # Default it uses Github flavoured markup as input and won't use coderay as converter for syntax highlighting.
+      # config: an hash of configuration options to be passed to the kramdown.
+      # usage:
+      # Add the kramdown gem to your gemfile or run:
+      # $ (sudo) gem install kramdown
+      #
+      # Then pass a new instance of GrapeSwagger::Markdown::KramdownAdapter as markdown option.
+      ###
+      def initialize(config = {})
+        require 'kramdown'
+        defaults = {
+          input: 'GFM',
+          enable_coderay: false
+        }
+        @options = defaults.merge(config)
+      rescue LoadError
+        raise GrapeSwagger::Errors::MarkdownDependencyMissingError, 'kramdown'
+      end
+
+      ###
+      # marks down the given text to html format.
+      # text: The text to be formatted.
+      ###
+      def markdown(text)
+        Kramdown::Document.new(text, @options).to_html
+      end
+    end
+  end
+end

data/lib/grape-swagger/markdown/redcarpet_adapter.rb

@@ -0,0 +1,89 @@
+module GrapeSwagger
+  class Markdown
+    class RedcarpetAdapter
+      module RenderWithoutSyntaxHighlighter
+        require 'cgi'
+
+        def block_code(code, language)
+          language ||= 'text'
+          "<div class=\"code_highlight\"><pre><code class=\"highlight #{language}\">#{CGI.escapeHTML(code)}</code></pre></div>"
+        end
+      end
+
+      attr_reader :extension_options
+
+      attr_reader :render_options
+
+      ###
+      # Initializes the redcarpet adapter with markup options.
+      # See redcarpet documentation what options can be passed.
+      # Default it uses fenced_code_blocks, autolinks and rouge as syntax highlighter.
+      # To configure an highlighter add {highlighter: :value} to the extentions hash.
+      # Currently supported highlighters:
+      #     :rouge
+      #
+      # extensions: an hash of configuration options to be passed to markdown.
+      # render_options: an hash of configuration options to be passed to renderer.
+      #
+      # usage:
+      # Add the redcarpet gem to your gemfile or run:
+      # $ (sudo) gem install redcarpet
+      # when you want to have rouge as syntax highlighter add rouge to the gemfile or run:
+      # $ (sudo) gem install rouge
+      #
+      # GrapeSwagger::Markdown::RedcarpetAdapter.new({highlighter: :none},{no_links: true}) # will use no syntax highlighter and won't render links.
+      ###
+      def initialize(options = {})
+        require 'redcarpet'
+        extentions_defaults = {
+          fenced_code_blocks: true,
+          autolink: true
+        }
+        render_defaults = { highlighter: :rouge }
+        @extension_options = extentions_defaults.merge(options.fetch(:extensions, {}))
+        @render_options = render_defaults.merge(options.fetch(:render_options, {}))
+        @renderer = new_redcarpet_renderer(@render_options.delete(:highlighter)).new(@render_options)
+        @markdown = Redcarpet::Markdown.new(@renderer, @extension_options)
+      rescue LoadError
+        raise GrapeSwagger::Errors::MarkdownDependencyMissingError, 'redcarpet'
+      end
+
+      ###
+      # Marks down the given text to html format.
+      ###
+      def markdown(text)
+        @markdown.render(text)
+      end
+
+      private
+
+      ###
+      # Creates a new redcarpet renderer based on the highlighter given.
+      #
+      # render_options: options passed to the renderer.
+      #
+      # usage:
+      # new_redcarpet_renderer(:rouge)  # uses rouge as highlighter.
+      # new_redcarpet_renderer          # no highlight plugin
+      ###
+      def new_redcarpet_renderer(syntax_highlighter = nil)
+        case syntax_highlighter
+        when :rouge
+          begin
+            Class.new(Redcarpet::Render::HTML) do
+              require 'rouge'
+              require 'rouge/plugins/redcarpet'
+              include Rouge::Plugins::Redcarpet
+            end
+          rescue LoadError
+            raise GrapeSwagger::Errors::MarkdownDependencyMissingError, 'rouge'
+          end
+        else
+          Class.new(Redcarpet::Render::HTML) do
+            include RenderWithoutSyntaxHighlighter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/version.rb

@@ -0,0 +1,3 @@
+module GrapeSwagger
+  VERSION = '0.8.0'
+end

data/spec/api_description_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe 'API Description' do
+  context 'with no additional options' do
+    subject do
+      Class.new(Grape::API) do
+        add_swagger_documentation
+      end
+    end
+
+    it 'describes the API with defaults' do
+      routes = subject.endpoints.first.routes
+      expect(routes.count).to eq 2
+      expect(routes.first.route_description).to eq 'Swagger compatible API description'
+      expect(routes.first.route_params).to eq({})
+      expect(routes.last.route_description).to eq 'Swagger compatible API description for specific API'
+      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'string', required: true })
+    end
+  end
+
+  context 'with additional options' do
+    subject do
+      Class.new(Grape::API) do
+        add_swagger_documentation \
+          api_documentation: { desc: 'First', params: { x: 1 }, xx: 11 },
+          specific_api_documentation: { desc: 'Second', params: { y: 42 }, yy: 4242 }
+      end
+    end
+
+    it 'describes the API with defaults' do
+      routes = subject.endpoints.first.routes
+      expect(routes.count).to eq 2
+      expect(routes.first.route_description).to eq 'First'
+      expect(routes.first.route_params).to eq(x: 1)
+      expect(routes.first.route_xx).to eq(11)
+      expect(routes.last.route_description).to eq 'Second'
+      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'string', required: true }, y: 42)
+      expect(routes.last.route_yy).to eq(4242)
+    end
+  end
+end

data/spec/api_global_models_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe 'Global Models' do
+
+  before :all do
+    module Entities
+      module Some
+        class Thing < Grape::Entity
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+        end
+
+        class CombinedThing < Grape::Entity
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+        end
+      end
+    end
+  end
+
+  subject do
+    Class.new(Grape::API) do
+      desc 'This gets thing.', params: Entities::Some::Thing.documentation
+      get '/thing' do
+        thing = OpenStruct.new text: 'thing'
+        present thing, with: Entities::Some::Thing
+      end
+
+      desc 'This gets combined thing.',
+           params: Entities::Some::CombinedThing.documentation,
+           entity: Entities::Some::CombinedThing
+      get '/combined_thing' do
+        thing = OpenStruct.new text: 'thing'
+        present thing, with: Entities::Some::CombinedThing
+      end
+
+      add_swagger_documentation models: [Entities::Some::Thing]
+    end
+  end
+
+  def app
+    subject
+  end
+
+  it 'includes models specified' do
+    get '/swagger_doc/thing.json'
+    json = JSON.parse(last_response.body)
+    expect(json['models']).to eq(
+        'Some::Thing' => {
+          'id' => 'Some::Thing',
+          'properties' => {
+            'text' => { 'type' => 'string', 'description' => 'Content of something.' }
+          }
+        })
+  end
+
+  it 'uses global models and route endpoint specific entities together' do
+    get '/swagger_doc/combined_thing.json'
+    json = JSON.parse(last_response.body)
+
+    expect(json['models']).to include(
+                                  'Some::Thing' => {
+                                    'id' => 'Some::Thing',
+                                    'properties' => {
+                                      'text' => { 'type' => 'string', 'description' => 'Content of something.' }
+                                    }
+                                  })
+
+    expect(json['models']).to include(
+                                  'Some::CombinedThing' => {
+                                    'id' => 'Some::CombinedThing',
+                                    'properties' => {
+                                      'text' => { 'type' => 'string', 'description' => 'Content of something.' }
+                                    }
+                                  })
+
+  end
+end

data/spec/api_models_spec.rb

@@ -1,132 +1,229 @@
 require 'spec_helper'
 
-describe "API Models" do
+describe 'API Models' do
 
   before :all do
     module Entities
       class Something < Grape::Entity
-        expose :text, :documentation => { :type => "string", :desc => "Content of something." }
+        expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+      end
+    end
+
+    module Entities
+      class EnumValues < Grape::Entity
+        expose :gender, documentation: { type: 'string', desc: 'Content of something.', values: %w(Male Female) }
+        expose :number, documentation: { type: 'integer', desc: 'Content of something.', values: proc { [1, 2] } }
       end
     end
 
     module Entities
       module Some
         class Thing < Grape::Entity
-          expose :text, :documentation => { :type => "string", :desc => "Content of something." }
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+        end
+      end
+    end
+
+    module Entities
+      class ComposedOf < Grape::Entity
+        expose :part_text, documentation: { type: 'string', desc: 'Content of composedof.' }
+      end
+
+      class ComposedOfElse < Grape::Entity
+        def self.entity_name
+          'composed'
         end
+        expose :part_text, documentation: { type: 'string', desc: 'Content of composedof else.' }
+      end
+
+      class SomeThingElse < Grape::Entity
+        expose :else_text, documentation: { type: 'string', desc: 'Content of something else.' }
+        expose :parts, using: Entities::ComposedOf, documentation: { type: 'ComposedOf',
+                                                                     is_array: true,
+                                                                     required: true }
+
+        expose :part, using: Entities::ComposedOfElse, documentation: { type: 'composes' }
+      end
+    end
+
+    module Entities
+      class AliasedThing < Grape::Entity
+        expose :something, as: :post, using: Entities::Something, documentation: { type: 'Something', desc: 'Reference to something.' }
       end
     end
+  end
 
-    class ModelsApi < Grape::API
+  def app
+    Class.new(Grape::API) do
       format :json
-      desc 'This gets something.', {
-        entity: Entities::Something
-      }
+      desc 'This gets something.', entity: Entities::Something
+
       get '/something' do
         something = OpenStruct.new text: 'something'
         present something, with: Entities::Something
       end
 
-      desc 'This gets thing.', {
-        entity: Entities::Some::Thing
-      }
-      get "/thing" do
+      desc 'This gets thing.', entity: Entities::Some::Thing
+      get '/thing' do
         thing = OpenStruct.new text: 'thing'
         present thing, with: Entities::Some::Thing
       end
+
+      desc 'This gets somthing else.', entity: Entities::SomeThingElse
+      get '/somethingelse' do
+        part = OpenStruct.new part_text: 'part thing'
+        thing = OpenStruct.new else_text: 'else thing', parts: [part], part: part
+
+        present thing, with: Entities::SomeThingElse
+      end
+
+      desc 'This tests the enum values in params and documentation.', entity: Entities::EnumValues, params: Entities::EnumValues.documentation
+      get '/enum_description_in_entity' do
+
+        enum_value = OpenStruct.new gender: 'Male', number: 1
+
+        present enum_value, with: Entities::EnumValues
+      end
+
+      desc 'This gets an aliased thing.', entity: Entities::AliasedThing
+      get '/aliasedthing' do
+        something = OpenStruct.new(something: OpenStruct.new(text: 'something'))
+        present something, with: Entities::AliasedThing
+      end
+
       add_swagger_documentation
     end
   end
 
-  def app; ModelsApi; end
-
-  it "should document specified models" do
-    get '/swagger_doc'
-    JSON.parse(last_response.body).should == {
-      "apiVersion" => "0.1",
-      "swaggerVersion" => "1.2",
-      "basePath" => "http://example.org",
-      "info" => {},
-      "produces" => ["application/json"],
-      "operations" => [],
-      "apis" => [
-        { "path" => "/swagger_doc/something.{format}" },
-        { "path" => "/swagger_doc/thing.{format}" },
-        { "path" => "/swagger_doc/swagger_doc.{format}" }
+  context 'swagger_doc' do
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    it 'returns a swagger-compatible doc' do
+      expect(subject).to include(
+        'apiVersion' => '0.1',
+        'swaggerVersion' => '1.2',
+        'info' => {},
+        'produces' => ['application/json']
+      )
+    end
+
+    it 'documents apis' do
+      expect(subject['apis']).to eq [
+        { 'path' => '/something.{format}', 'description' => 'Operations about somethings' },
+        { 'path' => '/thing.{format}', 'description' => 'Operations about things' },
+        { 'path' => '/somethingelse.{format}', 'description' => 'Operations about somethingelses' },
+        { 'path' => '/enum_description_in_entity.{format}', 'description' => 'Operations about enum_description_in_entities' },
+        { 'path' => '/aliasedthing.{format}', 'description' => 'Operations about aliasedthings' },
+        { 'path' => '/swagger_doc.{format}', 'description' => 'Operations about swagger_docs' }
       ]
-    }
+    end
   end
 
-  it "should include type when specified" do
+  it 'returns type' 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/json"
-          ],
-          "notes" => "",
-          "type" => "Something",
-          "summary" => "This gets something.",
-          "nickname" => "GET-something---format-",
-          "httpMethod" => "GET",
-          "parameters" => []
-        }]
-      }],
-      "models" => {
-        "Something" => {
-          "id" => "Something",
-          "name" => "Something",
-          "properties" => {
-            "text" => {
-              "type" => "string",
-              "description" => "Content of something."
-            }
-          }
-        }
-      }
-    }
+    result = JSON.parse(last_response.body)
+    expect(result['apis'].first['operations'].first['type']).to eq 'Something'
   end
 
-  it "should include nested type when specified" do
+  it 'includes nested type' do
     get '/swagger_doc/thing.json'
-    JSON.parse(last_response.body).should == {
-      "apiVersion" => "0.1",
-      "swaggerVersion" => "1.2",
-      "basePath" => "http://example.org",
-      "resourcePath" => "",
-      "apis" => [{
-        "path" => "/thing.{format}",
-        "operations" => [{
-          "produces" => [
-            "application/json"
-          ],
-          "notes" => "",
-          "type" => "Some::Thing",
-          "summary" => "This gets thing.",
-          "nickname" => "GET-thing---format-",
-          "httpMethod" => "GET",
-          "parameters" => []
-        }]
-      }],
-      "models" => {
-        "Some::Thing" => {
-          "id" => "Some::Thing",
-          "name" => "Some::Thing",
-          "properties" => {
-            "text" => {
-              "type" => "string",
-              "description" => "Content of something."
-            }
-          }
-        }
-      }
-    }
+    result = JSON.parse(last_response.body)
+    expect(result['apis'].first['operations'].first['type']).to eq 'Some::Thing'
+  end
+
+  it 'includes entities which are only used as composition' do
+    get '/swagger_doc/somethingelse.json'
+    result = JSON.parse(last_response.body)
+    expect(result['apis']).to eq([{
+                                   'path' => '/somethingelse.{format}',
+                                   'operations' => [{
+                                     'notes' => '',
+                                     'type' => 'SomeThingElse',
+                                     'summary' => 'This gets somthing else.',
+                                     'nickname' => 'GET-somethingelse---format-',
+                                     'method' => 'GET',
+                                     'parameters' => []
+                                   }]
+                                 }])
+
+    expect(result['models']['SomeThingElse']).to include('id' => 'SomeThingElse',
+                                                         'properties' => {
+                                                           'else_text' => {
+                                                             'type' => 'string',
+                                                             'description' => 'Content of something else.'
+                                                           },
+                                                           'parts' => {
+                                                             'type' => 'array',
+                                                             'items' => { '$ref' => 'ComposedOf' }
+                                                           },
+                                                           'part' => { '$ref' => 'composes' }
+                                                         },
+                                                         'required' => ['parts']
+
+                                                 )
+
+    expect(result['models']['ComposedOf']).to include(
+                                                        'id' => 'ComposedOf',
+                                                        'properties' => {
+                                                          'part_text' => {
+                                                            'type' => 'string',
+                                                            'description' => 'Content of composedof.'
+                                                          }
+                                                        }
+                                                      )
+
+    expect(result['models']['composed']).to include(
+                                                      'id' => 'composed',
+                                                      'properties' => {
+                                                        'part_text' => {
+                                                          'type' => 'string',
+                                                          'description' => 'Content of composedof else.'
+                                                        }
+
+                                                      }
+                                                    )
   end
 
+  it 'includes enum values in params and documentation.' do
+    get '/swagger_doc/enum_description_in_entity.json'
+    result = JSON.parse(last_response.body)
+    expect(result['models']['EnumValues']).to eq(
+                                                  'id' => 'EnumValues',
+                                                  'properties' => {
+                                                    'gender' => { 'type' => 'string', 'description' => 'Content of something.', 'enum' => %w(Male Female) },
+                                                    'number' => { 'type' => 'integer', 'description' => 'Content of something.', 'enum' => [1, 2] }
+                                                  }
+                                              )
+
+    expect(result['apis'][0]['operations'][0]).to include(
+                                                      'parameters' =>
+                                                         [
+                                                           { 'paramType' => 'query', 'name' => 'gender', 'description' => 'Content of something.', 'type' => 'string', 'required' => false, 'allowMultiple' => false, 'enum' => %w(Male Female) },
+                                                           { 'paramType' => 'query', 'name' => 'number', 'description' => 'Content of something.', 'type' => 'integer', 'required' => false, 'allowMultiple' => false, 'format' => 'int32', 'enum' => [1, 2] }
+                                                         ],
+                                                      'type' => 'EnumValues'
+                                                  )
+
+  end
+
+  it 'includes referenced models in those with aliased references.' do
+    get '/swagger_doc/aliasedthing.json'
+    result = JSON.parse(last_response.body)
+    expect(result['models']['AliasedThing']).to eq(
+                                                    'id' => 'AliasedThing',
+                                                    'properties' => {
+                                                      'post' => { '$ref' => 'Something', 'description' => 'Reference to something.' }
+                                                    }
+                                                )
+
+    expect(result['models']['Something']).to eq(
+                                                 'id' => 'Something',
+                                                 'properties' => {
+                                                   'text' => { 'type' => 'string', 'description' => 'Content of something.' }
+                                                 }
+                                             )
+  end
 end