apipie-rails 0.5.19 → 1.3.0

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

@@ -0,0 +1,63 @@
+class Apipie::Generator::Swagger::Schema
+  # @param [Array<Apipie::ResourceDescription>] resource_descriptions
+  def initialize(resource_descriptions, version:, language:, clear_warnings:)
+    @resource_descriptions = resource_descriptions
+    @language = language
+    @clear_warnings = clear_warnings
+    @swagger = {
+      swagger: '2.0',
+      info: {
+        title: Apipie.configuration.app_name.to_s,
+        description: "#{Apipie.app_info(version, @language)}#{Apipie.configuration.copyright}",
+        version: version.to_s,
+        'x-copyright': Apipie.configuration.copyright
+      },
+      basePath: Apipie.api_base_url(version),
+      consumes: [],
+      paths: {},
+      definitions: {},
+      schemes: Apipie.configuration.generator.swagger.schemes,
+      tags: [],
+      securityDefinitions: Apipie.configuration.generator.swagger.security_definitions,
+      security: Apipie.configuration.generator.swagger.global_security
+    }
+  end
+
+  def generate
+    if Apipie.configuration.generator.swagger.api_host.present?
+      @swagger[:host] = Apipie.configuration.generator.swagger.api_host
+    end
+
+    if Apipie.configuration.generator.swagger.content_type_input == :json
+      @swagger[:consumes] = ['application/json']
+      @swagger[:info][:title] += ' (params in:body)'
+    else
+      @swagger[:consumes] = ['application/x-www-form-urlencoded', 'multipart/form-data']
+      @swagger[:info][:title] += ' (params in:formData)'
+    end
+
+    if @clear_warnings
+      Apipie::Generator::Swagger::WarningWriter.instance.clear!
+    end
+
+    @swagger.merge!(tags_and_paths)
+
+    if Apipie.configuration.generator.swagger.generate_x_computed_id_field?
+      @swagger[:info]['x-computed-id'] =
+        Apipie::Generator::Swagger::ComputedInterfaceId.instance.id
+    end
+
+    @swagger[:definitions] =
+      Apipie::Generator::Swagger::ReferencedDefinitions.instance.definitions
+
+    @swagger
+  end
+
+  private
+
+  def tags_and_paths
+    Apipie::Generator::Swagger::ResourceDescriptionComposite
+      .new(@resource_descriptions, language: @language)
+      .to_swagger
+  end
+end

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

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

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

@@ -0,0 +1,16 @@
+class Apipie::Generator::Swagger::Type
+  attr_reader :str_format
+
+  def initialize(type, str_format = nil)
+    @type = type
+    @str_format = str_format
+  end
+
+  def to_s
+    @type
+  end
+
+  def ==(other)
+    other.to_s == self.to_s
+  end
+end

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

@@ -0,0 +1,51 @@
+class Apipie::Generator::Swagger::TypeExtractor
+  TYPES = {
+    numeric: 'number',
+    hash: 'object',
+    array: 'array',
+    enum: 'enum',
+
+    # see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
+    integer: Apipie::Generator::Swagger::Type.new('integer', 'int32'),
+    long: Apipie::Generator::Swagger::Type.new('integer', 'int64'),
+    number: Apipie::Generator::Swagger::Type.new('number'),
+    float: Apipie::Generator::Swagger::Type.new('number', 'float'),
+    double: Apipie::Generator::Swagger::Type.new('number', 'double'),
+    string: Apipie::Generator::Swagger::Type.new('string'),
+    byte: Apipie::Generator::Swagger::Type.new('string', 'byte'),
+    binary: Apipie::Generator::Swagger::Type.new('string', 'binary'),
+    boolean: Apipie::Generator::Swagger::Type.new('boolean'),
+    date: Apipie::Generator::Swagger::Type.new('string', 'date'),
+    dateTime: Apipie::Generator::Swagger::Type.new('string', 'date-time'),
+    password: Apipie::Generator::Swagger::Type.new('string', 'password')
+  }
+
+  # @param [Apipie::Validator::BaseValidator, ResponseDescriptionAdapter::PropDesc::Validator, nil] validator
+  def initialize(validator)
+    @validator = validator
+  end
+
+  def extract
+    expected_type =
+      if string?
+        :string
+      elsif enum?
+        :enum
+      else
+        @validator.expected_type.to_sym
+      end
+
+    TYPES[expected_type] || @validator.expected_type
+  end
+
+  private
+
+  def string?
+    @validator.blank?
+  end
+
+  def enum?
+    @validator.is_a?(Apipie::Validator::EnumValidator) ||
+      (@validator.respond_to?(:is_enum?) && @validator.is_enum?)
+  end
+end

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

@@ -0,0 +1,74 @@
+class Apipie::Generator::Swagger::Warning
+  MISSING_METHOD_SUMMARY_CODE = 100
+  ADDED_MISSING_SLASH_CODE = 101
+  NO_RETURN_CODES_SPECIFIED_CODE = 102
+  HASH_WITHOUT_INTERNAL_TYPESPEC_CODE = 103
+  OPTIONAL_PARAM_IN_PATH_CODE = 104
+  OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE = 105
+  PARAM_IGNORED_IN_FORM_DATA_CODE = 106
+  PATH_PARAM_NOT_DESCRIBED_CODE = 107
+
+  CODES = {
+    missing_method_summary: MISSING_METHOD_SUMMARY_CODE,
+    added_missing_slash: ADDED_MISSING_SLASH_CODE,
+    no_return_codes_specified: NO_RETURN_CODES_SPECIFIED_CODE,
+    hash_without_internal_typespec: HASH_WITHOUT_INTERNAL_TYPESPEC_CODE,
+    optional_param_in_path: OPTIONAL_PARAM_IN_PATH_CODE,
+    optional_without_default_value: OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE,
+    param_ignored_in_form_data: PARAM_IGNORED_IN_FORM_DATA_CODE,
+    path_param_not_described_code: PATH_PARAM_NOT_DESCRIBED_CODE
+  }
+
+  MESSAGES = {
+    MISSING_METHOD_SUMMARY_CODE => "Missing short description for method",
+    ADDED_MISSING_SLASH_CODE => "Added missing / at beginning of path: %{path}",
+    HASH_WITHOUT_INTERNAL_TYPESPEC_CODE => "The parameter :%{parameter} is a generic Hash without an internal type specification",
+    NO_RETURN_CODES_SPECIFIED_CODE => "No return codes ('errors') specified",
+    OPTIONAL_PARAM_IN_PATH_CODE => "The parameter :%{parameter} is 'in-path'.  Ignoring 'not required' in DSL",
+    OPTIONAL_WITHOUT_DEFAULT_VALUE_CODE => "The parameter :%{parameter} is optional but default value is not specified (use :default_value => ...)",
+    PARAM_IGNORED_IN_FORM_DATA_CODE => "Ignoring param :%{parameter} -- cannot include Hash without fields in a formData specification",
+    PATH_PARAM_NOT_DESCRIBED_CODE => "The parameter :%{name} appears in the path %{path} but is not described"
+  }
+
+  attr_reader :code
+
+  def initialize(code, info_message, method_id)
+    @code = code
+    @info_message = info_message
+    @method_id = method_id
+  end
+
+  def id
+    "#{@method_id}#{@code}#{@info_message}"
+  end
+
+  def warning_message
+    "WARNING (#{@code}): [#{@method_id}] -- #{@info_message}\n"
+  end
+
+  def warn
+    Warning.warn(warning_message)
+  end
+
+  def warn_through_writer
+    Apipie::Generator::Swagger::WarningWriter.instance.warn(self)
+  end
+
+  # @param [Integer] code
+  # @param [Hash] message_attributes
+  #
+  # @return [Apipie::Generator::Swagger::Warning]
+  def self.for_code(code, method_id, message_attributes = {})
+    if !CODES.value?(code)
+      raise ArgumentError, 'Unknown warning code'
+    end
+
+    info_message = if message_attributes.present?
+                     self::MESSAGES[code] % message_attributes
+                   else
+                     self::MESSAGES[code]
+                   end
+
+    Apipie::Generator::Swagger::Warning.new(code, info_message, method_id)
+  end
+end

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

@@ -0,0 +1,54 @@
+class Apipie::Generator::Swagger::WarningWriter
+  include Singleton
+
+  def initialize
+    @issued_warnings = []
+  end
+
+  # @param [Apipie::Generator::Swagger::Warning] warning
+  def warn(warning)
+    return if muted_warning?(warning)
+
+    warning.warn
+
+    @issued_warnings << warning.id
+  end
+
+  def issued_warnings?
+    @issued_warnings.count > 0
+  end
+
+  def clear!
+    @issued_warnings = []
+
+    self
+  end
+
+  private
+
+  # @param [Apipie::Generator::Swagger::Warning] warning
+  #
+  # @return [TrueClass, FalseClass]
+  def muted_warning?(warning)
+    @issued_warnings.include?(warning.id) ||
+      suppressed_warning?(warning.code) ||
+      suppress_warnings?
+  end
+
+  # @param [Integer] warning_number
+  #
+  # @return [TrueClass, FalseClass]
+  def suppressed_warning?(warning_number)
+    suppress_warnings_config.is_a?(Array) && suppress_warnings_config.include?(warning_number)
+  end
+
+  # @return [TrueClass, FalseClass]
+  def suppress_warnings?
+    suppress_warnings_config == true
+  end
+
+  # @return [FalseClass, TrueClass, Array]
+  def suppress_warnings_config
+    Apipie.configuration.generator.swagger.suppress_warnings
+  end
+end

data/lib/apipie/helpers.rb

@@ -25,10 +25,10 @@ module Apipie
         @url_prefix << request_script_name
         @url_prefix << Apipie.configuration.doc_base_url
       end
-      path = path.sub(/^\//,"")
+      path = path.sub(%r{^/},"")
       ret = "#{@url_prefix}/#{path}"
-      ret.insert(0,"/") unless ret =~ /\A[.\/]/
-      ret.sub!(/\/*\Z/,"")
+      ret.insert(0,"/") unless ret =~ %r{\A[./]}
+      ret.sub!(%r{/*\Z},"")
       ret
     end
 

data/lib/apipie/markup.rb

@@ -4,6 +4,11 @@ module Apipie
 
     class RDoc
 
+      def initialize
+        require 'rdoc'
+        require 'rdoc/markup/to_html'
+      end
+
       def to_html(text)
         rdoc.convert(text)
       end
@@ -11,14 +16,10 @@ module Apipie
       private
 
       def rdoc
-        @rdoc ||= begin
-          require 'rdoc'
-          require 'rdoc/markup/to_html'
-          if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
-            ::RDoc::Markup::ToHtml.new()
-          else
-            ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
-          end
+        if Gem::Version.new(::RDoc::VERSION) < Gem::Version.new('4.0.0')
+          ::RDoc::Markup::ToHtml.new()
+        else
+          ::RDoc::Markup::ToHtml.new(::RDoc::Options.new)
         end
       end
     end

data/lib/apipie/method_description/api.rb

@@ -0,0 +1,12 @@
+class Apipie::MethodDescription::Api
+  attr_accessor :short_description, :path, :http_method, :from_routes,
+    :options, :returns
+
+  def initialize(method, path, desc, options)
+    @http_method = method.to_s
+    @path = path
+    @short_description = desc
+    @from_routes = options[:from_routes]
+    @options = options
+  end
+end

data/lib/apipie/method_description/apis_service.rb

@@ -0,0 +1,82 @@
+# Service that builds the appropriate Apipie::MethodDescription::Api
+# required by Apipie::MethodDescription
+#
+class Apipie::MethodDescription::ApisService
+  # @param [Apipie::ResourceDescription] resource
+  # @param [Symbol] controller_action
+  # @param [Hash] dsl
+  def initialize(resource, controller_action, dsl)
+    @resource = resource
+    @controller_action = controller_action
+    @dsl = dsl
+  end
+
+  # @return [Array<Apipie::MethodDescription::Api>]
+  def call
+    api_args.map do |http_method, path, desc, opts|
+      Apipie::MethodDescription::Api.new(
+        http_method,
+        concern_subst(path),
+        concern_subst(desc),
+        opts
+      )
+    end
+  end
+
+  private
+
+  def concern_subst(path)
+    return if path.blank?
+
+    if from_concern?
+      @resource.controller._apipie_perform_concern_subst(path)
+    else
+      path
+    end
+  end
+
+  # @return [Array<Array>]
+  def api_args
+    return @dsl[:api_args] if !api_from_routes?
+
+    api_args = @dsl[:api_args].dup
+
+    api_args_from_routes = routes.map do |route_info|
+      [
+        route_info[:verb],
+        route_info[:path],
+        route_info[:desc],
+        (route_info[:options] || {}).merge(from_routes: true)
+      ]
+    end
+
+    api_args.concat(api_args_from_routes)
+  end
+
+  def api_from_routes?
+    @dsl[:api_from_routes].present?
+  end
+
+  def from_concern?
+    @dsl[:from_concern] == true
+  end
+
+  def description
+    @dsl[:api_from_routes][:desc]
+  end
+
+  def options
+    @dsl[:api_from_routes][:options]
+  end
+
+  # @return [Array<Hash>]
+  def routes
+    Apipie.routes_for_action(
+      @resource.controller,
+      @controller_action,
+      { desc: description, options: options }
+    )
+  end
+end
+
+

data/lib/apipie/method_description.rb

@@ -1,22 +1,5 @@
-require 'set'
 module Apipie
-
   class MethodDescription
-
-    class Api
-
-      attr_accessor :short_description, :path, :http_method, :from_routes, :options, :returns
-
-      def initialize(method, path, desc, options)
-        @http_method = method.to_s
-        @path = path
-        @short_description = desc
-        @from_routes = options[:from_routes]
-        @options = options
-      end
-
-    end
-
     attr_reader :full_description, :method, :resource, :apis, :examples, :see, :formats, :headers, :show
     attr_accessor :metadata
 
@@ -24,12 +7,9 @@ module Apipie
       @method = method.to_s
       @resource = resource
       @from_concern = dsl_data[:from_concern]
-      @apis = api_data(dsl_data).map do |mthd, path, desc, opts|
-        MethodDescription::Api.new(mthd, concern_subst(path), concern_subst(desc), opts)
-      end
+      @apis = ApisService.new(resource, method, dsl_data).call
 
-      desc = dsl_data[:description] || ''
-      @full_description = Apipie.markup_to_html(desc)
+      @full_description = dsl_data[:description] || ''
 
       @errors = dsl_data[:errors].map do |args|
         Apipie::ErrorDescription.from_dsl_data(args)
@@ -53,12 +33,12 @@ module Apipie
 
       @params_ordered = dsl_data[:params].map do |args|
         Apipie::ParamDescription.from_dsl_data(self, args)
-      end.reject{|p| p.response_only? }
+      end.reject(&:response_only?)
 
       @params_ordered = ParamDescription.unify(@params_ordered)
       @headers = dsl_data[:headers]
 
-      @show = if dsl_data.has_key? :show
+      @show = if dsl_data.key? :show
         dsl_data[:show]
       else
         true
@@ -102,7 +82,7 @@ module Apipie
       parent = Apipie.get_resource_description(@resource.controller.superclass)
 
       # get tags from parent resource description
-      parent_tags = [parent, @resource].compact.flat_map { |resource| resource._tag_list_arg }
+      parent_tags = [parent, @resource].compact.flat_map(&:_tag_list_arg)
       Apipie::TagListDescription.new((parent_tags + @tag_list).uniq.compact)
     end
 
@@ -178,14 +158,14 @@ module Apipie
       @formats || @resource._formats
     end
 
-    def to_json(lang=nil)
+    def to_json(lang = nil)
       {
         :doc_url => doc_url,
         :name => @method,
         :apis => method_apis_to_json(lang),
         :formats => formats,
-        :full_description => Apipie.app.translate(@full_description, lang),
-        :errors => errors.map(&:to_json),
+        :full_description => Apipie.markup_to_html(Apipie.app.translate(@full_description, lang)),
+        :errors => errors.map{ |error| error.to_json(lang) }.flatten,
         :params => params_ordered.map{ |param| param.to_json(lang) }.flatten,
         :returns => @returns.map{ |return_item| return_item.to_json(lang) }.flatten,
         :examples => @examples,
@@ -201,25 +181,12 @@ module Apipie
       @from_concern
     end
 
-    private
-
-    def api_data(dsl_data)
-      ret = dsl_data[:api_args].dup
-      if dsl_data[:api_from_routes]
-        desc = dsl_data[:api_from_routes][:desc]
-        options = dsl_data[:api_from_routes][:options]
-
-        api_from_routes = Apipie.routes_for_action(resource.controller, method, {:desc => desc, :options => options}).map do |route_info|
-          [route_info[:verb],
-           route_info[:path],
-           route_info[:desc],
-           (route_info[:options] || {}).merge(:from_routes => true)]
-        end
-        ret.concat(api_from_routes)
-      end
-      ret
+    def method_name
+      @method
     end
 
+    private
+
     def merge_params(params, new_params)
       new_param_names = Set.new(new_params.map(&:name))
       params.delete_if { |p| new_param_names.include?(p.name) }
@@ -259,16 +226,5 @@ module Apipie
       example << "\n" << format_example_data(ex[:response_data]).to_s if ex[:response_data]
       example
     end
-
-    def concern_subst(string)
-      return if string.nil?
-      if from_concern?
-        resource.controller._apipie_perform_concern_subst(string)
-      else
-        string
-      end
-    end
-
   end
-
 end

data/lib/apipie/param_description/deprecation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Apipie
+  class ParamDescription
+    # Data transfer object, used when param description is deprecated
+    class Deprecation
+      attr_reader :info, :deprecated_in, :sunset_at
+
+      def initialize(info: nil, deprecated_in: nil, sunset_at: nil)
+        @info = info
+        @deprecated_in = deprecated_in
+        @sunset_at = sunset_at
+      end
+
+      def to_json(*_args)
+        {
+          info: @info,
+          deprecated_in: @deprecated_in,
+          sunset_at: @sunset_at
+        }
+      end
+    end
+  end
+end