apipie-rails 0.9.4 → 1.0.0

data/lib/apipie/generator/swagger/config.rb

@@ -0,0 +1,78 @@
+require 'singleton'
+
+module Apipie
+  module Generator
+    module Swagger
+      class Config
+        include Singleton
+
+        CONFIG_ATTRIBUTES = [:include_warning_tags, :content_type_input,
+                             :json_input_uses_refs, :suppress_warnings, :api_host,
+                             :generate_x_computed_id_field, :allow_additional_properties_in_response,
+                             :responses_use_refs, :schemes, :security_definitions,
+                             :global_security].freeze
+
+        attr_accessor(*CONFIG_ATTRIBUTES)
+
+        CONFIG_ATTRIBUTES.each do |attribute|
+          old_setter_method = "swagger_#{attribute}="
+          define_method(old_setter_method) do |value|
+            ActiveSupport::Deprecation.warn(
+              <<~HEREDOC
+                config.#{old_setter_method}#{value} is deprecated.
+                config.generator.swagger.#{attribute} instead.
+              HEREDOC
+            )
+
+            send("#{attribute}=", value)
+          end
+
+          old_setter_method = "swagger_#{attribute}"
+          define_method(old_setter_method) do
+            ActiveSupport::Deprecation.warn(
+              <<~HEREDOC
+                config.#{old_setter_method} is deprecated.
+                Use config.generator.swagger.#{attribute} instead.
+              HEREDOC
+            )
+
+            send(attribute)
+          end
+        end
+
+        alias include_warning_tags? include_warning_tags
+        alias json_input_uses_refs? json_input_uses_refs
+        alias responses_use_refs? responses_use_refs
+        alias generate_x_computed_id_field? generate_x_computed_id_field
+        alias swagger_include_warning_tags? swagger_include_warning_tags
+        alias swagger_json_input_uses_refs? swagger_json_input_uses_refs
+        alias swagger_responses_use_refs? swagger_responses_use_refs
+        alias swagger_generate_x_computed_id_field? swagger_generate_x_computed_id_field
+
+        def initialize
+          @content_type_input = :form_data # this can be :json or :form_data
+          @json_input_uses_refs = false
+          @include_warning_tags = false
+          @suppress_warnings = false # [105,100,102]
+          @api_host = 'localhost:3000'
+          @generate_x_computed_id_field = false
+          @allow_additional_properties_in_response = false
+          @responses_use_refs = true
+          @schemes = [:https]
+          @security_definitions = {}
+          @global_security = []
+        end
+
+        def self.deprecated_methods
+          CONFIG_ATTRIBUTES.map do |attribute|
+            [
+              :"swagger_#{attribute}=",
+              :"swagger_#{attribute}?",
+              :"swagger_#{attribute}"
+            ]
+          end.flatten
+        end
+      end
+    end
+  end
+end

data/lib/apipie/generator/swagger/context.rb

@@ -1,10 +1,12 @@
 class Apipie::Generator::Swagger::Context
-  attr_reader :default_in_value, :language, :http_method, :controller_method
+  attr_reader :default_in_value, :language, :http_method, :controller_method,
+              :prefix
 
   def initialize(
     allow_null:,
     http_method:,
     controller_method:,
+    prefix: nil,
     default_in_value: nil,
     language: nil,
     in_schema: true
@@ -15,6 +17,7 @@ class Apipie::Generator::Swagger::Context
     @in_schema = in_schema
     @http_method = http_method
     @controller_method = controller_method
+    @prefix = prefix
   end
 
   def allow_null?
@@ -24,4 +27,12 @@ class Apipie::Generator::Swagger::Context
   def in_schema?
     @in_schema == true
   end
+
+  def add_to_prefix!(prefix)
+    @prefix = if @prefix.present?
+                "#{@prefix}[#{prefix}]"
+              else
+                prefix
+              end
+  end
 end

data/lib/apipie/generator/swagger/method_description/api_decorator.rb

@@ -0,0 +1,20 @@
+class Apipie::Generator::Swagger::MethodDescription::ApiDecorator < SimpleDelegator
+  def normalized_http_method
+    @normalized_http_method ||= http_method.downcase
+  end
+
+  def summary(method_description:, language:)
+    s = Apipie.app.translate(short_description, language)
+
+    if s.blank?
+      Apipie::Generator::Swagger::Warning.for_code(
+        Apipie::Generator::Swagger::Warning::MISSING_METHOD_SUMMARY_CODE,
+        method_description.ruby_name
+      ).warn_through_writer
+
+      nil
+    else
+      s
+    end
+  end
+end

data/lib/apipie/generator/swagger/method_description/api_schema_service.rb

@@ -0,0 +1,86 @@
+class Apipie::Generator::Swagger::MethodDescription::ApiSchemaService
+  # @param [Apipie::Generator::Swagger::MethodDescription::Decorator] method_description
+  def initialize(method_description, language: nil)
+    @method_description = method_description
+    @language = language
+  end
+
+  # @return [Hash]
+  def call
+    @method_description.apis.each_with_object({}) do |api, paths|
+      api = Apipie::Generator::Swagger::MethodDescription::ApiDecorator.new(api)
+      path = Apipie::Generator::Swagger::PathDecorator.new(api.path)
+      op_id = Apipie::Generator::Swagger::OperationId.from(api).to_s
+
+      if Apipie.configuration.generator.swagger.generate_x_computed_id_field?
+        Apipie::Generator::Swagger::ComputedInterfaceId.instance.add!(op_id)
+      end
+
+      parameters = Apipie::Generator::Swagger::MethodDescription::ParametersService
+                   .new(@method_description, path: path, http_method: api.normalized_http_method)
+                   .call
+
+      paths[path.swagger_path(@method_description)] ||= {}
+      paths[path.swagger_path(@method_description)][api.normalized_http_method] = {
+        tags: tags,
+        consumes: consumes,
+        operationId: op_id,
+        summary: api.summary(method_description: @method_description, language: @language),
+        parameters: parameters,
+        responses: responses(api),
+        description: Apipie.app.translate(@method_description.full_description, @language)
+      }.compact
+    end
+  end
+
+  private
+
+  def summary(api)
+    translated_description = Apipie.app.translate(api.short_description, @language)
+
+    return translated_description if translated_description.present?
+
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::MISSING_METHOD_SUMMARY_CODE,
+      @method_description.ruby_name
+    ).warn_through_writer
+  end
+
+  def tags
+    [@method_description.resource._id] +
+      warning_tags +
+      @method_description.tag_list.tags
+  end
+
+  def warning_tags
+    if Apipie.configuration.generator.swagger.include_warning_tags? &&
+       Apipie::Generator::Swagger::WarningWriter.instance.issued_warnings?
+      ['warnings issued']
+    else
+      []
+    end
+  end
+
+  def consumes
+    if params_in_body?
+      ['application/json']
+    else
+      ['application/x-www-form-urlencoded', 'multipart/form-data']
+    end
+  end
+
+  def params_in_body?
+    Apipie.configuration.generator.swagger.content_type_input == :json
+  end
+
+  # @param [Apipie::Generator::Swagger::MethodDescription::ApiDecorator] api
+  def responses(api)
+    Apipie::Generator::Swagger::MethodDescription::ResponseService
+      .new(
+        @method_description,
+        language: @language,
+        http_method: api.normalized_http_method
+      )
+      .call
+  end
+end

data/lib/apipie/generator/swagger/method_description/decorator.rb

@@ -0,0 +1,22 @@
+class Apipie::Generator::Swagger::MethodDescription::Decorator < SimpleDelegator
+  # @return [String]
+  def operation_id
+    "#{object.resource.controller.name}__#{object.method_name}"
+  end
+
+  # @return [String]
+  def ruby_name
+    if object.blank?
+      '<no method>'
+    else
+      "#{object.resource.controller.name}##{object.method_name}"
+    end
+  end
+
+  private
+
+  # @return [Apipie::MethodDescription, nil]
+  def object
+    __getobj__
+  end
+end

data/lib/apipie/generator/swagger/method_description/parameters_service.rb

@@ -0,0 +1,139 @@
+class Apipie::Generator::Swagger::MethodDescription::ParametersService
+  # @param [Apipie::Generator::Swagger::MethodDescription::Decorator] method_description
+  # @param [Apipie::Generator::Swagger::PathDecorator] path
+  # @param [Symbol] http_method
+  def initialize(method_description, path:, http_method:)
+    @method_description = method_description
+    @path = path
+    @http_method = http_method
+  end
+
+  # @return [Array]
+  def call
+    path_params_schema + body_params_schema + header_params_schema
+  end
+
+  private
+
+  def path_params_schema
+    Apipie::Generator::Swagger::ParamDescription::PathParamsComposite.new(
+      path_param_descriptions,
+      Apipie::Generator::Swagger::Context.new(
+        allow_null: false,
+        default_in_value: 'path',
+        http_method: @http_method,
+        controller_method: @method_description
+      )
+    ).to_swagger
+  end
+
+  def body_params_schema
+    if params_in_body? && body_allowed_for_current_method?
+      composite = Apipie::Generator::Swagger::ParamDescription::Composite.new(
+        body_param_descriptions,
+        Apipie::Generator::Swagger::Context.new(
+          allow_null: false,
+          http_method: @http_method,
+          controller_method: @method_description
+        )
+      )
+
+      if Apipie.configuration.generator.swagger.json_input_uses_refs?
+        composite = composite
+                    .referenced("#{@method_description.operation_id}_input")
+      end
+
+      swagger_schema_for_body = composite.to_swagger
+
+      swagger_body_param = {
+        name: 'body',
+        in: 'body',
+        schema: swagger_schema_for_body
+      }
+
+      if swagger_schema_for_body.present?
+        [swagger_body_param]
+      else
+        []
+      end
+    else
+      Apipie::Generator::Swagger::ParamDescription::PathParamsComposite.new(
+        body_param_descriptions,
+        Apipie::Generator::Swagger::Context.new(
+          allow_null: false,
+          http_method: @http_method,
+          controller_method: @method_description
+        )
+      ).to_swagger
+    end
+  end
+
+  def all_params
+    @all_params ||=
+      begin
+        param_names_from_method = @method_description.params.keys
+        missing = @path.param_names - param_names_from_method
+
+        result = @method_description.params
+
+        missing.each do |name|
+          warn_path_parameter_not_described(name, @path)
+
+          result[name.to_sym] = Apipie::Generator::Swagger::ParamDescription
+                                .create_for_missing_param(@method_description, name)
+        end
+
+        result
+      end
+  end
+
+  def body_param_descriptions
+    @body_param_descriptions ||= all_params
+                                 .reject { |k, _| @path.param?(k) }
+                                 .values
+  end
+
+  def path_param_descriptions
+    @path_param_descriptions ||= all_params
+                                 .select { |k, _| @path.param?(k) }
+                                 .each { |_, desc| desc.required = true }
+                                 .values
+  end
+
+  # @return [Array]
+  def header_params_schema
+    return [] if @method_description.headers.blank?
+
+    @method_description.headers.map do |header|
+      header_hash = {
+        name: header[:name],
+        in: 'header',
+        required: header[:options][:required],
+        description: header[:description],
+        type: header[:options][:type] || 'string'
+
+      }
+      if header[:options][:default]
+        header_hash[:default] = header[:options][:default]
+      end
+
+      header_hash
+    end
+  end
+
+  def params_in_body?
+    Apipie.configuration.generator.swagger.content_type_input == :json
+  end
+
+  def body_allowed_for_current_method?
+    %w[get head].exclude?(@http_method)
+  end
+
+  def warn_path_parameter_not_described(name, path)
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::PATH_PARAM_NOT_DESCRIBED_CODE,
+      @method_description.ruby_name,
+      { name: name, path: path }
+    ).warn_through_writer
+  end
+end

data/lib/apipie/generator/swagger/method_description/response_schema_service.rb

@@ -0,0 +1,46 @@
+class Apipie::Generator::Swagger::MethodDescription::ResponseSchemaService
+  # @param [Apipie::ResponseDescription, Apipie::ResponseDescriptionAdapter] response_description
+  def initialize(response_description, allow_null:, http_method:, controller_method:)
+    @response_description = response_description
+    @allow_null = allow_null
+    @http_method = http_method
+    @controller_method = controller_method
+  end
+
+  def to_swagger
+    composite = Apipie::Generator::Swagger::ParamDescription::Composite.new(
+      @response_description.params_ordered,
+      Apipie::Generator::Swagger::Context.new(
+        allow_null: @allow_null,
+        http_method: @http_method,
+        controller_method: @controller_method
+      )
+    )
+
+    if Apipie.configuration.generator.swagger.responses_use_refs? && @response_description.typename.present?
+      composite = composite.referenced(@response_description.typename)
+    end
+
+    schema = composite.to_swagger
+
+    if @response_description.is_array? && schema
+      schema = { type: type_for_array, items: schema }
+    end
+
+    if @response_description.allow_additional_properties
+      schema[:additionalProperties] = true
+    end
+
+    schema
+  end
+
+  private
+
+  def type_for_array
+    if @allow_null == true
+      %w[array null]
+    else
+      'array'
+    end
+  end
+end

data/lib/apipie/generator/swagger/method_description/response_service.rb

@@ -0,0 +1,58 @@
+class Apipie::Generator::Swagger::MethodDescription::ResponseService
+  # @param [Apipie::Generator::Swagger::MethodDescription::Decorator] method_description
+  # @param [Symbol] http_method
+  def initialize(method_description, http_method:, language:)
+    @method_description = method_description
+    @http_method = http_method
+    @language = language
+  end
+
+  # @return [Hash]
+  def call
+    result = {}
+    result.merge!(errors)
+    result.merge!(responses)
+    result.merge!(empty_returns)
+
+    result
+  end
+
+  private
+
+  # @return [Hash]
+  def errors
+    @errors ||= @method_description.errors.each_with_object({}) do |error, errors|
+      errors[error.code] = {
+        description: Apipie.app.translate(error.description, @language)
+      }
+    end
+  end
+
+  # @return [Hash]
+  def responses
+    @responses ||=
+      @method_description.returns.each_with_object({}) do |response, responses_schema|
+        responses_schema[response.code] = {
+          description: Apipie.app.translate(response.description, @language),
+          schema: Apipie::Generator::Swagger::MethodDescription::ResponseSchemaService.new(
+            response,
+            allow_null: false,
+            http_method: @http_method,
+            controller_method: @method_description
+          ).to_swagger
+        }.compact
+      end
+  end
+
+  # @return [Hash]
+  def empty_returns
+    return {} if errors.present? || responses.present?
+
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::NO_RETURN_CODES_SPECIFIED_CODE,
+      @method_description.ruby_name
+    ).warn_through_writer
+
+    { 200 => { description: 'ok' } }
+  end
+end

data/lib/apipie/generator/swagger/method_description.rb

@@ -0,0 +1,2 @@
+module Apipie::Generator::Swagger::MethodDescription
+end

data/lib/apipie/generator/swagger/operation_id.rb

@@ -22,7 +22,7 @@ class Apipie::Generator::Swagger::OperationId
   # @return [Apipie::Generator::Swagger::OperationId]
   def self.from(describable, param: nil)
     path, http_method =
-      if describable.is_a?(Apipie::MethodDescription::Api)
+      if describable.respond_to?(:path) && describable.respond_to?(:http_method)
         [describable.path, describable.http_method]
       elsif describable.is_a?(Apipie::MethodDescription)
         [describable.apis.first.path, describable.apis.first.http_method]

data/lib/apipie/generator/swagger/param_description/builder.rb

@@ -1,7 +1,7 @@
 class Apipie::Generator::Swagger::ParamDescription::Builder
   # @param [Apipie::ParamDescription] param_description
   # @param [TrueClass, FalseClass] in_schema
-  # @param [String] controller_method
+  # @param [Apipie::MethodDescription] controller_method
   def initialize(param_description, in_schema:, controller_method:)
     @param_description = param_description
     @in_schema = in_schema
@@ -88,16 +88,16 @@ class Apipie::Generator::Swagger::ParamDescription::Builder
 
   def warn_optional_without_default_value(definition)
     if !required? && !definition.key?(:default)
-      method =
+      method_id =
         if @param_description.is_a?(Apipie::ResponseDescriptionAdapter::PropDesc)
           @controller_method
         else
-          @param_description.method_description.method
+          Apipie::Generator::Swagger::MethodDescription::Decorator.new(@controller_method).ruby_name
         end
 
       Apipie::Generator::Swagger::Warning.for_code(
         Apipie::Generator::Swagger::Warning::OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
-        method,
+        method_id,
         { parameter: @param_description.name }
       ).warn_through_writer
     end

data/lib/apipie/generator/swagger/param_description/composite.rb

@@ -74,7 +74,7 @@ class Apipie::Generator::Swagger::ParamDescription::Composite
       end
     end
 
-    if !Apipie.configuration.swagger_allow_additional_properties_in_response
+    if !Apipie.configuration.generator.swagger.allow_additional_properties_in_response
       @schema[:additionalProperties] = false
     end
 
@@ -85,6 +85,14 @@ class Apipie::Generator::Swagger::ParamDescription::Composite
     @schema
   end
 
+  # @param [Symbol, String] param_type
+  #
+  # @return [Apipie::Generator::Swagger::ParamDescription::ReferencedComposite]
+  def referenced(param_type)
+    Apipie::Generator::Swagger::ParamDescription::ReferencedComposite.
+      new(self, param_type)
+  end
+
   private
 
   def for_array(schema)

data/lib/apipie/generator/swagger/param_description/in.rb

@@ -32,6 +32,6 @@ class Apipie::Generator::Swagger::ParamDescription::In
   end
 
   def body_allowed_for_current_method?
-    ['get', 'head'].exclude?(@http_method)
+    %w[get head].exclude?(@http_method)
   end
 end

data/lib/apipie/generator/swagger/param_description/path_params_composite.rb

@@ -0,0 +1,61 @@
+class Apipie::Generator::Swagger::ParamDescription::PathParamsComposite
+  # @param [Array<Apipie::ParamDescription>] param_descriptions
+  # @param [Apipie::Generator::Swagger::Context] context
+  def initialize(param_descriptions, context)
+    @param_descriptions = param_descriptions
+    @context = context
+    @result = []
+  end
+
+  # @return [Array]
+  def to_swagger
+    @param_descriptions.each do |desc|
+      context = @context.dup
+
+      type = Apipie::Generator::Swagger::TypeExtractor.new(desc.validator).extract
+
+      if type == 'object' && desc.validator.params_ordered.blank?
+        warn_param_ignored_in_form_data(desc.name)
+        next
+      end
+
+      has_nested_params = type == 'object' &&
+                          desc.validator.params_ordered.present?
+
+      if has_nested_params
+        context.add_to_prefix!(desc.name)
+
+        out = Apipie::Generator::Swagger::ParamDescription::PathParamsComposite
+              .new(desc.validator.params_ordered, context)
+              .to_swagger
+
+        @result.concat(out)
+      else
+        param_entry =
+          Apipie::Generator::Swagger::ParamDescription::Builder
+          .new(desc, in_schema: false, controller_method: context.controller_method)
+          .with_description(language: context.language)
+          .with_name(prefix: context.prefix)
+          .with_type(with_null: context.allow_null?)
+          .with_in(
+            http_method: context.http_method,
+            default_in_value: context.default_in_value
+          ).to_swagger
+
+        @result << param_entry
+      end
+    end
+
+    @result.sort_by { |p| p[:required] ? 0 : 1 }
+  end
+
+  private
+
+  def warn_param_ignored_in_form_data(name)
+    Apipie::Generator::Swagger::Warning.for_code(
+      Apipie::Generator::Swagger::Warning::PARAM_IGNORED_IN_FORM_DATA_CODE,
+      @context.controller_method.ruby_name,
+      { parameter: name }
+    ).warn_through_writer
+  end
+end

data/lib/apipie/generator/swagger/param_description/referenced_composite.rb

@@ -0,0 +1,36 @@
+# A Composite that keeps track when a param description has been added to references
+#   and returns the reference instead of the complete object
+class Apipie::Generator::Swagger::ParamDescription::ReferencedComposite
+  # @param [Apipie::Generator::Swagger::ParamDescription::Composite] composite
+  # @param [Symbol, String] param_type
+  def initialize(composite, param_type)
+    @composite = composite
+    @param_type = param_type.to_sym
+  end
+
+  def to_swagger
+    return ref_to(:name) if added?(:name)
+
+    schema_obj = @composite.to_swagger
+
+    return nil if schema_obj.nil?
+
+    add(schema_obj)
+
+    { '$ref' => ref_to(@param_type) }
+  end
+
+  private
+
+  def ref_to(name)
+    "#/definitions/#{name}"
+  end
+
+  def add(schema)
+    Apipie::Generator::Swagger::ReferencedDefinitions.instance.add!(@param_type, schema)
+  end
+
+  def added?(name)
+    Apipie::Generator::Swagger::ReferencedDefinitions.instance.added?(name)
+  end
+end

data/lib/apipie/generator/swagger/param_description/type.rb

@@ -44,7 +44,7 @@ class Apipie::Generator::Swagger::ParamDescription::Type
   private
 
   def params_in_body_use_reference?
-    Apipie.configuration.swagger_json_input_uses_refs
+    Apipie.configuration.generator.swagger.json_input_uses_refs
   end
 
   # @return [Apipie::Generator::Swagger::Type, String]
@@ -99,9 +99,16 @@ class Apipie::Generator::Swagger::ParamDescription::Type
   end
 
   def warn_hash_without_internal_typespec
+    method_id =
+      if @param_description.is_a?(Apipie::ResponseDescriptionAdapter::PropDesc)
+        @controller_method.method
+      else
+        Apipie::Generator::Swagger::MethodDescription::Decorator.new(@param_description.method_description).ruby_name
+      end
+
     Apipie::Generator::Swagger::Warning.for_code(
       Apipie::Generator::Swagger::Warning::HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
-      @controller_method,
+      method_id,
       { parameter: @param_description.name }
     ).warn_through_writer
   end