Merge pull request #351 from LeFnord/master

(re)adding some documentations

Author: peter scholz

CHANGELOG.md

@@ -1,5 +1,4 @@
-
-n.n.n / 2016-02-05
+n.n.n / 2016-02-14
 ==================
 
 ### 0.10.4 (Next)

README.md

@@ -9,7 +9,9 @@ This branch is work in progress for bringing grape-swagger to Swagger 2.0 spec.
 [Usage](#usage)  
 [Configure](#configure)  
 [Routes Configuration](#routes)  
-[Additional documentation](#additions)  
+[Markdown](#md_usage)  
+[Response documentation](#response)  
+[Extensions](#extensions)  
 [Example](#example)  
 
 For how to use at the moment see [v2 specs](tree/master/spec/swagger_v2) and or [Hussars](https://github.com/LeFnord/hussars) sample app.
@@ -681,24 +683,61 @@ The result is then something like following:
 },
 ```
 
+<a name="extensions" />
+## Extensions
 
-## direct adding of additional swagger information for the route
-
-- The amazon api gateway parameters can be added by indicated a aws hash with auth and integration keys, example:
+Swagger spec2.0 supports extensions on different levels, for the moment,
+the documentation on `verb`, `path` and `definition` level would be supported.
+The documented key would be generated from the `x` + `-` + key of the submitted hash,
+for possibilities refer to the [extensions spec](spec/lib/extensions_spec.rb).
+To get an overview *how* the extensions would be defined on grape level, see the following examples:
 
+- `verb` extension, add a `x` key to the `desc` hash:
 ```ruby
-desc 'thing',
-  aws: {
-    auth: 'aws_iam',
-    integration: {
-      type: 'aws',
-      uri: 'foo_bar_uri',
-      httpMethod: 'get'
-    }
+desc 'This returns something with extension on verb level',
+  x: { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "get":{
+    "…":"…",
+    "x-some":"stuff"
   }
+}
+```
 
-  …
+- `path` extension, by setting via route settings:
+```ruby
+route_setting :x_path, { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "x-some":"stuff",
+  "get":{
+    "…":"…",
+  }
+}
+```
 
+- `definition` extension, again by setting via route settings,
+here the status code must be provided, for which definition the extensions should be:
+```ruby
+route_setting :x_def, { for: 422, other: 'stuff' }
+```
+this would generate:
+```json
+"/definitions":{
+  "ApiError":{
+    "x-other":"stuff",
+    "…":"…",
+  }
+}
+```
+or, for more definitions:
+```ruby
+route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }]
 ```
 
 <a="example" />

example/api/entities.rb

@@ -4,8 +4,8 @@ module Api
   module Entities
     class Splines < Grape::Entity
       expose :id, documentation: { type: Integer, desc: 'identity of a resource' }
-      expose :x, documentation: { type: Numeric, desc: 'x-value' }
-      expose :y, documentation: { type: Numeric, desc: 'y-value' }
+      expose :x, documentation: { type: Float, desc: 'x-value' }
+      expose :y, documentation: { type: Float, desc: 'y-value' }
       expose :path, documentation: { type: String, desc: 'the requested resource'}
 
       private

lib/grape-swagger.rb

@@ -3,6 +3,8 @@
 require 'grape-swagger/endpoint'
 require 'grape-swagger/errors'
 require 'grape-swagger/doc_methods/produces'
+require 'grape-swagger/doc_methods/data_type'
+require 'grape-swagger/doc_methods/extensions'
 require 'grape-swagger/doc_methods'
 require 'grape-swagger/markdown/kramdown_adapter'
 require 'grape-swagger/markdown/redcarpet_adapter'

lib/grape-swagger/doc_methods/data_type.rb

@@ -0,0 +1,53 @@
+module GrapeSwagger
+  module DocMethods
+    class DataType
+      class << self
+        def call(value)
+          raw_data_type = value[:type] if value.is_a?(Hash)
+          raw_data_type ||= 'string'
+          case raw_data_type.to_s
+          when 'Hash'
+            'object'
+          when 'Rack::Multipart::UploadedFile'
+            'File'
+          when 'Virtus::Attribute::Boolean'
+            'boolean'
+          when 'Boolean', 'Date', 'Integer', 'String', 'Float'
+            raw_data_type.to_s.downcase
+          when 'BigDecimal'
+            'long'
+          when 'DateTime'
+            'dateTime'
+          when 'Numeric'
+            'double'
+          when 'Symbol'
+            'string'
+          else
+            parse_entity_name(raw_data_type)
+          end
+        end
+
+        def parse_entity_name(model)
+          if model.respond_to?(:entity_name)
+            model.entity_name
+          else
+            name = model.to_s
+            entity_parts = name.split('::')
+            entity_parts.reject! { |p| p == 'Entity' || p == 'Entities' }
+            entity_parts.join('::')
+          end
+        end
+      end
+
+      PRIMITIVE_MAPPINGS = {
+        'integer' => %w(integer int32),
+        'long' => %w(integer int64),
+        'float' => %w(number float),
+        'double' => %w(number double),
+        'byte' => %w(string byte),
+        'date' => %w(string date),
+        'dateTime' => %w(string date-time)
+      }.freeze
+    end
+  end
+end

lib/grape-swagger/doc_methods/extensions.rb

@@ -0,0 +1,75 @@
+module GrapeSwagger
+  module DocMethods
+    class Extensions
+      class << self
+        def add(path, definitions, route)
+          @route = route
+          description = route.route_settings[:description]
+          add_extension_to(path[method], extension(description)) if description && extended?(description, :x)
+
+          settings = route.route_settings
+          add_extensions_to_path(settings, path) if settings && extended?(settings, :x_path)
+          add_extensions_to_definition(settings, path, definitions) if settings && extended?(settings, :x_def)
+        end
+
+        def add_extensions_to_path(settings, path)
+          add_extension_to(path, extension(settings, :x_path))
+        end
+
+        def add_extensions_to_definition(settings, path, definitions)
+          def_extension = extension(settings, :x_def)
+
+          if def_extension[:x_def].is_a?(Array)
+            def_extension[:x_def].each do |extension|
+              next unless extension.key?(:for)
+              status = extension.delete(:for)
+              definition = find_definition(status, path)
+              add_extension_to(definitions[definition], x_def: extension)
+            end
+          else
+            return unless def_extension[:x_def].key?(:for)
+            status = def_extension[:x_def].delete(:for)
+            definition = find_definition(status, path)
+            add_extension_to(definitions[definition], def_extension)
+          end
+        end
+
+        def find_definition(status, path)
+          response = path[method][:responses][status]
+
+          response[:schema]['$ref'].split('/').last
+        end
+
+        def add_extension_to(part, extensions)
+          concatenate(extensions).each do |key, value|
+            part[key] = value
+          end
+        end
+
+        def concatenate(extensions)
+          result = {}
+
+          extensions.values.each do |extension|
+            extension.each do |key, value|
+              result["x-#{key}"] = value
+            end
+          end
+
+          result
+        end
+
+        def extended?(part, identifier = :x)
+          !extension(part, identifier).empty?
+        end
+
+        def extension(part, identifier = :x)
+          part.select { |x| x == identifier }
+        end
+
+        def method
+          @route.route_method.downcase.to_sym
+        end
+      end
+    end
+  end
+end