[WIP] Open api3 rebased

Gemfile

@@ -32,6 +32,7 @@ group :development, :test do
   gem 'rdoc'
   gem 'rspec', '~> 3.9'
   gem 'rubocop', '~> 1.50', require: false
+  gem "openapi3_parser", "~> 0.10.0"
 
   unless ENV['MODEL_PARSER'] == 'grape-swagger-entity'
     gem 'grape-swagger-entity', git: 'https://github.com/ruby-grape/grape-swagger-entity'

README.md

@@ -931,7 +931,7 @@ get '/thing', failure: [
   # ...
 end
 ```
-If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L210) would be taken.
+If no status code is defined [defaults](/lib/grape-swagger/swagger_2/endpoint.rb#L210) would be taken.
 
 The result is then something like following:
 

lib/grape-swagger.rb

@@ -4,12 +4,13 @@
 
 require 'grape-swagger/instance'
 
-require 'grape-swagger/version'
-require 'grape-swagger/endpoint'
 require 'grape-swagger/errors'
-
-require 'grape-swagger/doc_methods'
+require 'grape-swagger/version'
 require 'grape-swagger/model_parsers'
+require 'grape-swagger/swagger_2/endpoint'
+require 'grape-swagger/openapi_3/endpoint'
+require 'grape-swagger/openapi_3/doc_methods'
+require 'grape-swagger/swagger_2/doc_methods'
 
 module GrapeSwagger
   class << self
@@ -122,11 +123,10 @@ module SwaggerDocumentationAdder
   include SwaggerRouting
 
   def add_swagger_documentation(options = {})
-    documentation_class = create_documentation_class
-
-    version_for(options)
     options = { target_class: self }.merge(options)
+    version_for(options)
     @target_class = options[:target_class]
+    documentation_class = create_documentation_class(options[:openapi_version])
     auth_wrapper = options[:endpoint_auth_wrapper] || Class.new
 
     use auth_wrapper if auth_wrapper.method_defined?(:before) && !middleware.flatten.include?(auth_wrapper)
@@ -144,6 +144,10 @@ def add_swagger_documentation(options = {})
     @target_class.combined_routes = combined_routes
     @target_class.combined_namespaces = combined_namespaces
 
+    endpoint_type = options[:openapi_version] == '3.0' ? Grape::OpenAPI3Endpoint : Grape::Swagger2Endpoint
+    set_endpoint_type(@target_class, endpoint_type)
+    set_endpoint_type(documentation_class, endpoint_type)
+
     documentation_class
   end
 
@@ -153,6 +157,13 @@ def version_for(options)
     options[:version] = version if version
   end
 
+  def set_endpoint_type(app, klass)
+    app.endpoints.each do |endpoint|
+      endpoint.class.include(klass)
+      set_endpoint_type(endpoint.options[:app], klass) if endpoint.options[:app]
+    end
+  end
+
   def combine_namespaces(app)
     combined_namespaces = {}
     endpoints = app.endpoints.clone
@@ -174,9 +185,13 @@ def combine_namespaces(app)
     combined_namespaces
   end
 
-  def create_documentation_class
+  def create_documentation_class(openapi_version)
     Class.new(GrapeInstance) do
-      extend GrapeSwagger::DocMethods
+      if openapi_version == '3.0'
+        extend GrapeOpenAPI::DocMethods
+      else
+        extend GrapeSwagger::DocMethods
+      end
     end
   end
 end

lib/grape-swagger/doc_methods/extensions.rb

@@ -55,9 +55,17 @@ def find_definition(status, path)
           response = path[method][:responses][status]
           return if response.nil?
 
-          return response[:schema]['$ref'].split('/').last if response[:schema].key?('$ref')
+          # Swagger 2
+          if response[:schema]
+            return response[:schema]['$ref'].split('/').last if response[:schema].key?('$ref')
+            return response[:schema]['items']['$ref'].split('/').last if response[:schema].key?('items')
+          end
 
-          response[:schema]['items']['$ref'].split('/').last if response[:schema].key?('items')
+          # OpenAPI 3
+          response[:content].each do |_,v|
+            return v[:schema]['$ref'].split('/').last if v[:schema].key?('$ref')
+            return v[:schema]['items']['$ref'].split('/').last if v[:schema].key?('items')
+          end
         end
 
         def add_extension_to(part, extensions)

lib/grape-swagger/doc_methods/parse_params.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'grape-swagger/endpoint/info_object_builder'
+
 module GrapeSwagger
   module DocMethods
     class ParseParams

lib/grape-swagger/endpoint/info_object_builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module Endpoint
+    class InfoObjectBuilder
+      attr_reader :infos
+
+      def self.build(infos)
+        new(infos).build
+      end
+
+      def initialize(infos)
+        @infos = infos
+      end
+
+      def build
+        result = {
+          title: infos[:title] || 'API title',
+          description: infos[:description],
+          termsOfService: infos[:terms_of_service_url],
+          contact: contact_object,
+          license: license_object,
+          version: infos[:version]
+        }
+
+        GrapeSwagger::DocMethods::Extensions.add_extensions_to_info(infos, result)
+
+        result.delete_if { |_, value| value.blank? }
+      end
+
+      private
+
+      # sub-objects of info object
+      # license
+      def license_object
+        {
+          name: infos[:license],
+          url: infos[:license_url]
+        }.delete_if { |_, value| value.blank? }
+      end
+
+      # contact
+      def contact_object
+        {
+          name: infos[:contact_name],
+          email: infos[:contact_email],
+          url: infos[:contact_url]
+        }.delete_if { |_, value| value.blank? }
+      end
+    end
+  end
+end

lib/grape-swagger/openapi_3/doc_methods.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'grape-swagger/doc_methods/status_codes'
+require 'grape-swagger/doc_methods/produces_consumes'
+require 'grape-swagger/doc_methods/data_type'
+require 'grape-swagger/doc_methods/extensions'
+require 'grape-swagger/doc_methods/operation_id'
+require 'grape-swagger/doc_methods/optional_object'
+require 'grape-swagger/doc_methods/path_string'
+require 'grape-swagger/doc_methods/tag_name_description'
+require 'grape-swagger/openapi_3/doc_methods/parse_params'
+require 'grape-swagger/openapi_3/doc_methods/move_params'
+require 'grape-swagger/doc_methods/headers'
+require 'grape-swagger/doc_methods/build_model_definition'
+require 'grape-swagger/doc_methods/version'
+
+module GrapeOpenAPI
+  module DocMethods
+    def hide_documentation_path
+      @@hide_documentation_path
+    end
+
+    def mount_path
+      @@mount_path
+    end
+
+    def setup(options)
+      options = defaults.merge(options)
+
+      # options could be set on #add_swagger_documentation call,
+      # for available options see #defaults
+      target_class     = options[:target_class]
+      guard            = options[:swagger_endpoint_guard]
+      formatter        = options[:format]
+      api_doc          = options[:api_documentation].dup
+      specific_api_doc = options[:specific_api_documentation].dup
+
+      class_variables_from(options)
+
+      if formatter
+        %i[format default_format default_error_formatter].each do |method|
+          send(method, formatter)
+        end
+      end
+
+      desc api_doc.delete(:desc), api_doc
+
+      instance_eval(guard) unless guard.nil?
+
+      output_path_definitions = proc do |combi_routes, endpoint|
+        output = endpoint.swagger_object(
+          target_class,
+          endpoint.request,
+          options
+        )
+
+        paths, definitions   = endpoint.path_and_definition_objects(combi_routes, target_class, options)
+        tags                 = tags_from(paths, options)
+
+        output[:tags]        = tags unless tags.empty? || paths.blank?
+        output[:paths]       = paths unless paths.blank?
+        unless definitions.blank?
+          output[:components] ||= {}
+          output[:components][:schemas] = definitions
+        end
+
+        output
+      end
+
+      get mount_path do
+        header['Access-Control-Allow-Origin']   = '*'
+        header['Access-Control-Request-Method'] = '*'
+
+        output_path_definitions.call(target_class.combined_namespace_routes, self)
+      end
+
+      desc specific_api_doc.delete(:desc), { params:
+        specific_api_doc.delete(:params) || {} }.merge(specific_api_doc)
+
+      params do
+        requires :name, type: String, desc: 'Resource name of mounted API'
+        optional :locale, type: Symbol, desc: 'Locale of API documentation'
+      end
+
+      get "#{mount_path}/:name" do
+        I18n.locale = params[:locale] || I18n.default_locale
+
+        combined_routes = target_class.combined_namespace_routes[params[:name]]
+        error!({ error: 'named resource not exist' }, 400) if combined_routes.nil?
+
+        output_path_definitions.call({ params[:name] => combined_routes }, self)
+      end
+    end
+
+    def defaults
+      {
+        info: {},
+        models: [],
+        doc_version: '0.0.1',
+        target_class: nil,
+        mount_path: '/swagger_doc',
+        host: nil,
+        base_path: nil,
+        add_base_path: false,
+        add_version: true,
+        hide_documentation_path: true,
+        format: :json,
+        authorizations: nil,
+        security_definitions: nil,
+        security: nil,
+        api_documentation: { desc: 'Swagger compatible API description' },
+        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
+        endpoint_auth_wrapper: nil,
+        swagger_endpoint_guard: nil,
+        token_owner: nil
+      }
+    end
+
+    def class_variables_from(options)
+      @@mount_path              = options[:mount_path]
+      @@class_name              = options[:class_name] || options[:mount_path].delete('/')
+      @@hide_documentation_path = options[:hide_documentation_path]
+    end
+
+    def tags_from(paths, options)
+      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+
+      if options[:tags]
+        names = options[:tags].map { |t| t[:name] }
+        tags.reject! { |t| names.include?(t[:name]) }
+        tags += options[:tags]
+      end
+
+      tags
+    end
+  end
+end