scorpio 0.6.4 → 0.7.0

data/documents/swagger.io/v2/schema.json

@@ -203,7 +203,7 @@
       "additionalProperties": {
         "$ref": "#/definitions/response"
       },
-      "description": "One or more JSON representations for parameters"
+      "description": "One or more JSON representations for responses"
     },
     "externalDocs": {
       "type": "object",

data/documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest.yml

@@ -1,11 +1,12 @@
 ---
 kind: discovery#restDescription
-etag: '"YWOzh2SDasdU84ArJnpYek-OMdg/K3nEDF6hixE8Pks2-9Ysn9j9prQ"'
+etag: '"-2NioU2H8y8siEzrBOV_qzRI6kQ/vabF8Q1ADCm_Bt9EBq9rkrRawQA"'
+revision: '20200806'
 discoveryVersion: v1
 id: discovery:v1
 name: discovery
 version: v1
-title: APIs Discovery Service
+title: API Discovery Service
 description: Provides information about other Google APIs, such as what APIs are available, the resource, and method details for each API.
 ownerDomain: google.com
 ownerName: Google
@@ -48,11 +49,11 @@ parameters:
     location: query
   quotaUser:
     type: string
-    description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters. Overrides userIp if both are provided.
+    description: An opaque string that represents a user for quota purposes. Must not exceed 40 characters.
     location: query
   userIp:
     type: string
-    description: IP address of the site where the request originates. Use this if you want to enforce per-user limits.
+    description: Deprecated. Please use quotaUser instead.
     location: query
 schemas:
   DirectoryList:
@@ -210,6 +211,14 @@ schemas:
                   type: string
                 type_value:
                   type: string
+      enumDeprecated:
+        type: array
+        description: The deprecation status for the enums. Each position maps to the corresponding value in the "enum" array.
+        items:
+          type: boolean
+      deprecated:
+        type: boolean
+        description: Whether the parameter is deprecated.
   RestDescription:
     id: RestDescription
     type: object
@@ -345,6 +354,25 @@ schemas:
         description: The version of this API.
       version_module:
         type: boolean
+      endpoints:
+        type: array
+        description: A list of location-based endpoint objects for this API. Each object contains the endpoint URL, location, description and deprecation status.
+        items:
+          type: object
+          description: A single endpoint object
+          properties:
+            location:
+              type: string
+              description: The location of the endpoint
+            deprecated:
+              type: boolean
+              description: Whether this endpoint is deprecated
+            endpointUrl:
+              type: string
+              description: The URL of the endpoint target host
+            description:
+              type: string
+              description: A string describing the host designated by the URL
   RestMethod:
     id: RestMethod
     type: object
@@ -447,6 +475,15 @@ schemas:
       useMediaDownloadService:
         type: boolean
         description: Indicates that downloads from this method should use the download service URL (i.e. "/download"). Only applies if the method supports media download.
+      apiVersion:
+        type: string
+        description: The API Version of this method, as passed in via the `X-Goog-Api-Version` header or `$apiVersion` query parameter.
+      flatPath:
+        type: string
+        description: The URI path of this REST method in (RFC 6570) format without level 2 features ({+var}). Supplementary to the path property.
+      deprecated:
+        type: boolean
+        description: Whether this method is deprecated.
   RestResource:
     id: RestResource
     type: object
@@ -463,6 +500,9 @@ schemas:
         additionalProperties:
           "$ref": RestResource
           description: Description for any sub-resources on this resource.
+      deprecated:
+        type: boolean
+        description: Whether this resource is deprecated.
 resources:
   apis:
     methods:

data/lib/scorpio/google_api_document.rb

@@ -2,20 +2,22 @@
 
 module Scorpio
   module Google
-    discovery_rest_description_doc = ::JSON.parse(Scorpio.root.join('documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest').read)
-    discovery_rest_description = JSI::MetaSchemaNode.new(
+    discovery_rest_description_doc = YAML.safe_load(Scorpio.root.join('documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest.yml').read)
+    DISCOVERY_REST_DESCRIPTION = JSI.new_metaschema_node(
       discovery_rest_description_doc,
-      metaschema_root_ptr: JSI::Ptr['schemas']['JsonSchema'],
-      root_schema_ptr: JSI::Ptr['schemas']['RestDescription'],
-      schema_implementation_modules: [JSI::Schema::Draft04],
+      dialect: JSI::Schema::Draft04::DIALECT,
+      metaschema_root_ref: "#/schemas/JsonSchema",
+      root_schema_ref: "#/schemas/RestDescription",
     )
 
     # naming these is not strictly necessary, but is nice to have.
-    DirectoryList = discovery_rest_description.schemas['DirectoryList'].jsi_schema_module
-    JsonSchema     = discovery_rest_description.schemas['JsonSchema'].jsi_schema_module
-    RestDescription = discovery_rest_description.schemas['RestDescription'].jsi_schema_module
-    RestMethod     = discovery_rest_description.schemas['RestMethod'].jsi_schema_module
-    RestResource  = discovery_rest_description.schemas['RestResource'].jsi_schema_module
+
+
+    DirectoryList = DISCOVERY_REST_DESCRIPTION.schemas['DirectoryList'].jsi_schema_module
+    JsonSchema     = DISCOVERY_REST_DESCRIPTION.schemas['JsonSchema'].jsi_schema_module
+    RestDescription = DISCOVERY_REST_DESCRIPTION.schemas['RestDescription'].jsi_schema_module
+    RestMethod     = DISCOVERY_REST_DESCRIPTION.schemas['RestMethod'].jsi_schema_module
+    RestResource  = DISCOVERY_REST_DESCRIPTION.schemas['RestResource'].jsi_schema_module
 
     module RestDescription
       Resources = properties['resources']
@@ -24,197 +26,123 @@ module Scorpio
     module RestMethod
       Request = properties['request']
       Response = properties['response']
+
+      # these only contain a $ref to a schema, but that is enough to use them as schemas
+      Request.describes_schema!(JSI::Schema::Draft04::DIALECT)
+      Response.describes_schema!(JSI::Schema::Draft04::DIALECT)
     end
 
-    # google does a weird thing where it defines a schema with a $ref property where a json-schema is to be used in the document (method request and response fields), instead of just setting the schema to be the json-schema schema. we'll share a module across those schema classes that really represent schemas. is this confusingly meta enough?
-    module SchemaLike
-      def to_openapi
-        # openapi does not want an id field on schemas
-        dup_doc = jsi_node_content.reject { |k, _| k == 'id' }
-        if dup_doc['properties'].is_a?(Hash)
-          required_properties = []
-          dup_doc['properties'].each do |key, value|
-            if value.is_a?(Hash) && value.key?('required')
-              required_properties.push(key) if value['required']
-              dup_doc = dup_doc.merge({'properties' => value.reject { |vk, _| vk == 'required' }})
-            end
-          end
-          # put required before properties
-          unless required_properties.empty?
-            dup_doc = dup_doc.map do |k, v|
-              base = k == 'properties' ? {'required' => required_properties } : {}
-              base.merge({k => v})
-            end.inject({}, &:update)
-          end
+    module HasMethodsAndResources
+      def operations
+        return @operations if instance_variable_defined?(:@operations)
+        @operations = OpenAPI::OperationsScope.new(each_operation)
+      end
+
+      def each_operation(&block)
+        return(to_enum(__method__)) unless block
+
+        (self['methods'] || {}).each_value(&block)
+
+        (self['resources'] || {}).each_value do |resource|
+          resource.each_operation(&block)
         end
-        dup_doc
       end
     end
-    [JsonSchema, RestMethod::Request, RestMethod::Response].each { |m| m.send(:include, SchemaLike) }
 
     module RestDescription
-      def to_openapi_document(options = {})
-        Scorpio::OpenAPI::Document.from_instance(to_openapi_hash(options))
-      end
-
-      def to_openapi_hash(options = {})
-        ad = self
-        ad_methods = []
-        if ad['methods']
-          ad_methods += ad['methods'].map do |mn, m|
-            m.tap do
-              m.send(:define_singleton_method, :resource_name) { }
-              m.send(:define_singleton_method, :method_name) { mn }
-            end
-          end
-        end
-        ad_methods += ad.resources.map do |rn, r|
-          (r['methods'] || {}).map do |mn, m|
-            m.tap do
-              m.send(:define_singleton_method, :resource_name) { rn }
-              m.send(:define_singleton_method, :method_name) { mn }
-            end
-          end
-        end.inject([], &:+)
-
-        paths = ad_methods.group_by { |m| m['path'] }.map do |path, path_methods|
-          unless path =~ %r(\A/)
-            path = '/' + path
-          end
-          operations = path_methods.group_by { |m| m['httpMethod'] }.map do |http_method, http_method_methods|
-            if http_method_methods.size > 1
-              #raise("http method #{http_method} at path #{path} not unique: #{http_method_methods.pretty_inspect}")
-            end
-            method = http_method_methods.first
-            unused_path_params = Addressable::Template.new(path).variables
-            {http_method.downcase => {}.tap do |operation|
-              operation['tags'] = method.resource_name ? [method.resource_name] : []
-              #operation['summary'] = 
-              operation['description'] = method['description'] if method['description']
-              #operation['externalDocs'] = 
-              operation['operationId'] = method['id'] || (method.resource_name ? "#{method.resource_name}.#{method.method_name}" : method.method_name)
-              #operation['produces'] = 
-              #operation['consumes'] = 
-              if method['parameters']
-                operation['parameters'] = method['parameters'].map do |name, parameter|
-                  {}.tap do |op_param|
-                    op_param['description'] = parameter.description if parameter.description
-                    op_param['name'] = name
-                    op_param['in'] = if parameter.location
-                      parameter.location
-                    elsif unused_path_params.include?(name)
-                      'path'
-                    else
-                      'query'
-                    # unused: header, formdata, body
-                    end
-                    unused_path_params.delete(name) if op_param['in'] == 'path'
-                    op_param['required'] = parameter.key?('required') ? parameter['required'] : op_param['in'] == 'path' ? true : false
-                    op_param['type'] = parameter.type || 'string'
-                    op_param['format'] = parameter['format'] if parameter['format']
-                  end
-                end
-              end
-              if unused_path_params.any?
-                operation['parameters'] ||= []
-                operation['parameters'] += unused_path_params.map do |param_name|
-                  {
-                    'name' => param_name,
-                    'in' => 'path',
-                    'required' => true,
-                    'type' => 'string',
-                  }
-                end
-              end
-              if method['request']
-                operation['parameters'] ||= []
-                operation['parameters'] << {
-                  'name' => 'body',
-                  'in' => 'body',
-                  'required' => true,
-                  'schema' => method['request'],
-                }
-              end
-              if method['response']
-                operation['responses'] = {
-                  'default' => {
-                    'description' => 'default response',
-                    'schema' => method['response'],
-                  },
-                }
-              end
-            end}
-          end.inject({}, &:update)
-
-          {path => operations}
-        end.inject({}, &:update)
-
-        openapi = {
-          'swagger' => '2.0',
-          'info' => { #/definitions/info
-            'title' => ad.title || ad.name,
-            'description' => ad.description,
-            'version' => ad.version || '',
-            #'termsOfService' => '',
-            'contact' => {
-              'name' => ad.ownerName,
-              #'url' => 
-              #'email' => '',
-            }.reject { |_, v| v.nil? },
-            #'license' => {
-              #'name' => '',
-              #'url' => '',
-            #},
-          },
-          'host' => ad.rootUrl ? Addressable::URI.parse(ad.rootUrl).host : ad.baseUrl ? Addressable::URI.parse(ad.baseUrl).host : ad.name, # uhh ... got nothin' better
-          'basePath' => begin
-            path = ad.servicePath || ad.basePath || (ad.baseUrl ? Addressable::URI.parse(ad.baseUrl).path : '/')
-            path =~ %r(\A/) ? path : "/" + path
-          end,
-          'schemes' => ad.rootUrl ? [Addressable::URI.parse(ad.rootUrl).scheme] : ad.baseUrl ? [Addressable::URI.parse(ad.rootUrl).scheme] : [], #/definitions/schemesList
-          'consumes' => ['application/json'], # we'll just make this assumption
-          'produces' => ['application/json'],
-          'tags' => paths.flat_map { |_, p| p.flat_map { |_, op| (op['tags'] || []).map { |n| {'name' => n} } } }.uniq,
-          'paths' => paths, #/definitions/paths
-        }
-        if ad.schemas
-          openapi['definitions'] = ad.schemas
-          ad.schemas.each do |name, schema|
-            openapi = JSI::Util.ycomb do |rec|
-              proc do |object|
-                if object.respond_to?(:to_hash)
-                  object.merge(object.map do |k, v|
-                    if k == '$ref' && (v == schema['id'] || v == "#/schemas/#{name}" || v == name)
-                      {k => "#/definitions/#{name}"}
-                    else
-                      JSI::Util.ycomb do |toopenapirec|
-                        proc do |toopenapiobject|
-                          toopenapiobject = toopenapiobject.to_openapi if toopenapiobject.respond_to?(:to_openapi)
-                          if toopenapiobject.respond_to?(:to_hash)
-                            toopenapiobject.map { |k2, v2| {toopenapirec.call(k2) => toopenapirec.call(v2)} }.inject({}, &:update)
-                          elsif toopenapiobject.respond_to?(:to_ary)
-                            toopenapiobject.map(&toopenapirec)
-                          elsif toopenapiobject.is_a?(Symbol)
-                            toopenapiobject.to_s
-                          elsif [String, TrueClass, FalseClass, NilClass, Numeric].any? { |c| toopenapiobject.is_a?(c) }
-                            toopenapiobject
-                          else
-                            raise(TypeError, "bad (not jsonifiable) object: #{toopenapiobject.pretty_inspect}")
-                          end
-                        end
-                      end.call({k => rec.call(v)})
-                    end
-                  end.inject({}, &:merge))
-                elsif object.respond_to?(:to_ary)
-                  object.map(&rec)
-                else
-                  object
-                end
-              end
-            end.call(openapi)
-          end
+      include(OpenAPI::Document)
+      include(HasMethodsAndResources)
+
+      attr_writer(:base_url)
+
+      def base_url(scheme: nil, server: nil, server_variables: nil)
+        return @base_url if instance_variable_defined?(:@base_url)
+        JSI::Util.uri(rootUrl ? File.join(rootUrl, servicePath) : baseUrl) # baseUrl is deprecated
+      end
+
+      def title
+        self['title'] # override OpenAPI::Document#title
+      end
+    end
+
+    module RestResource
+      include(HasMethodsAndResources)
+    end
+
+    module RestMethod
+      include(OpenAPI::Operation)
+
+      def tagged?(tag_name)
+        resource_names.include?(tag_name)
+      end
+
+      def resource_names
+        # resource name is the property name where a RestResource is. kind of hax but it works.
+        jsi_parent_nodes.select { |n| n.is_a?(RestResource) }.map { |r| r.jsi_ptr.tokens.last }
+      end
+
+      def path_template_str
+        path
+      end
+
+      def parameters
+        (self['parameters'] || {}).map do |name, schema|
+          param = {'name' => name}
+          param['in'] = schema.location if schema.key?('location')
+          param['schema'] = schema
+          #param['description'] = schema.description if schema.key?('description')
+          #param['required'] = schema.required if schema.key?('required')
+          param
         end
-        JSI::Util.as_json(openapi)
+      end
+
+      def request_media_type
+        'application/json'
+      end
+
+      def http_method
+        httpMethod
+      end
+
+      def openapi_document
+        rest_description
+      end
+
+      def rest_description
+        jsi_parent_nodes.detect { |p| p.is_a?(RestDescription) }
+      end
+
+      def scheme
+        nil
+      end
+
+      def server
+        nil
+      end
+
+      def server_variables
+        nil
+      end
+
+      def operationId
+        id
+      end
+
+      # @param media_type unused
+      def request_schema(media_type: nil)
+        request
+      end
+
+      def request_schemas
+        request ? [request] : []
+      end
+
+      def response_schema(status: nil, media_type: nil)
+        response
+      end
+
+      def response_schemas
+        response ? [response] : []
       end
     end
   end

data/lib/scorpio/openapi/document.rb

@@ -12,17 +12,21 @@ module Scorpio
         # instantiating it.
         #
         # @param instance [#to_hash] the document to represent as a Scorpio OpenAPI Document
-        # @return [Scorpio::OpenAPI::V2::Document, Scorpio::OpenAPI::V3::Document]
-        def from_instance(instance)
+        # @return [JSI::Base + Scorpio::OpenAPI::Document]
+        def new_document(instance, **new_param)
           if instance.is_a?(Scorpio::OpenAPI::Document)
             instance
           elsif instance.is_a?(JSI::Base)
-            raise(TypeError, "instance is unexpected JSI type: #{instance.class.inspect}")
+            raise(TypeError, -"instance is unexpected JSI type: #{instance.class.inspect}")
           elsif instance.respond_to?(:to_hash)
-            if instance['swagger'] =~ /\A2(\.|\z)/
-              instance = Scorpio::OpenAPI::V2::Document.new_jsi(instance)
-            elsif instance['openapi'] =~ /\A3(\.|\z)/
-              instance = Scorpio::OpenAPI::V3::Document.new_jsi(instance)
+            if (instance['swagger'].is_a?(String) && instance['swagger'] =~ /\A2(\.|\z)/) || instance['swagger'] == 2
+              Scorpio::OpenAPI::V2::Document.new_jsi(instance, **new_param)
+            elsif (instance['openapi'].is_a?(String) && instance['openapi'] =~ /\A3\.0(\.|\z)/) || instance['openapi'] == 3.0
+              Scorpio::OpenAPI::V3_0::Document.new_jsi(instance, **new_param)
+            elsif (instance['openapi'].is_a?(String) && instance['openapi'] =~ /\A3\.1(\.|\z)/) || instance['openapi'] == 3.1
+              Scorpio::OpenAPI::V3_1.new_document(instance, **new_param)
+            elsif instance['kind'] == 'discovery#restDescription'
+              Scorpio::Google::RestDescription.new_jsi(instance, register: true, **new_param)
             else
               raise(ArgumentError, "instance does not look like a recognized openapi document")
             end
@@ -30,6 +34,18 @@ module Scorpio
             raise(TypeError, "instance does not look like a hash (json object)")
           end
         end
+
+        # @deprecated after v0.8.0. use `new_document`.
+        def from_instance(instance, **kw)
+          Scorpio.new_document(instance, **kw)
+        end
+      end
+
+      module Descendent
+        # @return [Scorpio::OpenAPI::Document]
+        def openapi_document
+          jsi_ancestor_nodes.detect { |n| n.is_a?(OpenAPI::Document) } || raise(Error, -"not inside an OpenAPI document (#{inspect})")
+        end
       end
 
       module Configurables
@@ -42,13 +58,25 @@ module Scorpio
         attr_writer :user_agent
         def user_agent
           return @user_agent if instance_variable_defined?(:@user_agent)
-          "Scorpio/#{Scorpio::VERSION} (https://github.com/notEthan/scorpio) Faraday/#{Faraday::VERSION} Ruby/#{RUBY_VERSION}"
+          Request::DEFAULT_USER_AGENT
+        end
+
+        attr_writer(:accept)
+        def accept
+          return @accept if instance_variable_defined?(:@accept)
+          nil
+        end
+
+        attr_writer(:authorization)
+        def authorization
+          return @authorization if instance_variable_defined?(:@authorization)
+          nil
         end
 
         attr_writer :faraday_builder
         def faraday_builder
           return @faraday_builder if instance_variable_defined?(:@faraday_builder)
-          -> (_) { }
+          nil
         end
 
         attr_writer :faraday_adapter
@@ -66,26 +94,37 @@ module Scorpio
       include Configurables
 
       def v2?
-        is_a?(V2::Document)
+        is_a?(OpenAPI::V2::Document)
       end
 
       def v3?
-        is_a?(V3::Document)
+        is_a?(OpenAPI::Document::V3Methods)
       end
 
       def operations
         return @operations if instance_variable_defined?(:@operations)
-        @operations = OperationsScope.new(self)
+        @operations = OperationsScope.new(each_operation)
+      end
+
+      def each_operation(&block)
+        return(to_enum(__method__)) unless block
+
+        paths.each do |path, path_item|
+          path_item.each do |http_method, operation|
+            if operation.is_a?(Scorpio::OpenAPI::Operation)
+              yield(operation)
+            end
+          end
+        end
       end
-    end
 
-    module V3
-      raise(Bug, 'const_defined? Scorpio::OpenAPI::V3::Document') unless const_defined?(:Document)
+      def title
+        info && info.title
+      end
+    end
 
-      # A document that defines or describes an API conforming to the OpenAPI Specification v3.
-      #
-      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#oasObject
-      module Document
+    module Document
+      module V3Methods
         module Configurables
           def scheme
             nil
@@ -112,23 +151,15 @@ module Scorpio
             end
           end
 
-          attr_writer :request_media_type
-          def request_media_type
-            return @request_media_type if instance_variable_defined?(:@request_media_type)
-            nil
-          end
+          attr_accessor(:request_media_type)
         end
         include Configurables
+        include(OpenAPI::Document)
       end
     end
 
-    module V2
-      raise(Bug, 'const_defined? Scorpio::OpenAPI::V2::Document') unless const_defined?(:Document)
-
-      # A document that defines or describes an API conforming to the OpenAPI Specification v2 (aka Swagger).
-      #
-      # The root document is known as the Swagger Object.
-      module Document
+    module Document
+      module V2Methods
         module Configurables
           attr_writer :scheme
           def scheme
@@ -174,6 +205,7 @@ module Scorpio
           end
         end
         include Configurables
+        include(OpenAPI::Document)
       end
     end
   end