scorpio 0.0.4 → 0.1.0

data/{getRest.yml → documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest.yml}

@@ -1,13 +1,12 @@
-# retrieved from 
+---
 kind: discovery#restDescription
-etag: '"C5oy1hgQsABtYOYIOXWcR3BgYqU/Pyg0A4J33Dq212hoe9BYpSm0dl4"'
+etag: '"YWOzh2SDasdU84ArJnpYek-OMdg/K3nEDF6hixE8Pks2-9Ysn9j9prQ"'
 discoveryVersion: v1
 id: discovery:v1
 name: discovery
 version: v1
 title: APIs Discovery Service
-description: Provides information about other Google APIs, such as what APIs are available,
-  the resource, and method details for each API.
+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
 icons:
@@ -19,7 +18,7 @@ baseUrl: https://www.googleapis.com/discovery/v1/
 basePath: "/discovery/v1/"
 rootUrl: https://www.googleapis.com/
 servicePath: discovery/v1/
-batchPath: batch
+batchPath: batch/discovery/v1
 parameters:
   alt:
     type: string
@@ -36,8 +35,7 @@ parameters:
     location: query
   key:
     type: string
-    description: API key. Your API key identifies your project and provides you with
-      API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
+    description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
     location: query
   oauth_token:
     type: string
@@ -50,14 +48,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: 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.
     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: IP address of the site where the request originates. Use this if you want to enforce per-user limits.
     location: query
 schemas:
   DirectoryList:
@@ -66,8 +61,7 @@ schemas:
     properties:
       discoveryVersion:
         type: string
-        description: Indicate the version of the Discovery API used to generate this
-          doc.
+        description: Indicate the version of the Discovery API used to generate this doc.
         default: v1
       items:
         type: array
@@ -131,20 +125,17 @@ schemas:
     properties:
       "$ref":
         type: string
-        description: A reference to another schema. The value of this property is
-          the "id" of another schema.
+        description: A reference to another schema. The value of this property is the "id" of another schema.
       additionalProperties:
         "$ref": JsonSchema
-        description: If this is a schema for an object, this property is the schema
-          for any additional properties with dynamic keys on this object.
+        description: If this is a schema for an object, this property is the schema for any additional properties with dynamic keys on this object.
       annotations:
         type: object
         description: Additional information about this property.
         properties:
           required:
             type: array
-            description: A list of methods for which this property is required on
-              requests.
+            description: A list of methods for which this property is required on requests.
             items:
               type: string
       default:
@@ -160,25 +151,21 @@ schemas:
           type: string
       enumDescriptions:
         type: array
-        description: The descriptions for the enums. Each position maps to the corresponding
-          value in the "enum" array.
+        description: The descriptions for the enums. Each position maps to the corresponding value in the "enum" array.
         items:
           type: string
       format:
         type: string
-        description: 'An additional regular expression or key that helps constrain
-          the value. For more details see: http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.23'
+        description: 'An additional regular expression or key that helps constrain the value. For more details see: http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.23'
       id:
         type: string
         description: Unique identifier for this schema.
       items:
         "$ref": JsonSchema
-        description: If this is a schema for an array, this property is the schema
-          for each element in the array.
+        description: If this is a schema for an array, this property is the schema for each element in the array.
       location:
         type: string
-        description: Whether this parameter goes in the query or the path for REST
-          requests.
+        description: Whether this parameter goes in the query or the path for REST requests.
       maximum:
         type: string
         description: The maximum value of this parameter.
@@ -187,21 +174,16 @@ schemas:
         description: The minimum value of this parameter.
       pattern:
         type: string
-        description: 'The regular expression this parameter must conform to. Uses
-          Java 6 regex format: http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html'
+        description: 'The regular expression this parameter must conform to. Uses Java 6 regex format: http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html'
       properties:
         type: object
-        description: If this is a schema for an object, list the schema for each property
-          of this object.
+        description: If this is a schema for an object, list the schema for each property of this object.
         additionalProperties:
           "$ref": JsonSchema
-          description: A single property of this object. The value is itself a JSON
-            Schema object describing this property.
+          description: A single property of this object. The value is itself a JSON Schema object describing this property.
       readOnly:
         type: boolean
-        description: The value is read-only, generated by the service. The value cannot
-          be modified by the client. If the value is included in a POST, PUT, or PATCH
-          request, it is ignored by the service.
+        description: The value is read-only, generated by the service. The value cannot be modified by the client. If the value is included in a POST, PUT, or PATCH request, it is ignored by the service.
       repeated:
         type: boolean
         description: Whether this parameter may appear multiple times.
@@ -210,13 +192,10 @@ schemas:
         description: Whether the parameter is required.
       type:
         type: string
-        description: 'The value type for this schema. A list of values can be found
-          here: http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.1'
+        description: 'The value type for this schema. A list of values can be found here: http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.1'
       variant:
         type: object
-        description: In a variant data type, the value of one property is used to
-          determine how to interpret the entire entity. Its value must exist in a
-          map of descriminant values to schema names.
+        description: In a variant data type, the value of one property is used to determine how to interpret the entire entity. Its value must exist in a map of descriminant values to schema names.
         properties:
           discriminant:
             type: string
@@ -262,18 +241,15 @@ schemas:
       batchPath:
         type: string
         description: The path for REST batch requests.
-        default: batch
       canonicalName:
         type: string
-        description: Indicates how the API name should be capitalized and split into
-          various parts. Useful for generating pretty class names.
+        description: Indicates how the API name should be capitalized and split into various parts. Useful for generating pretty class names.
       description:
         type: string
         description: The description of this API.
       discoveryVersion:
         type: string
-        description: Indicate the version of the Discovery API used to generate this
-          doc.
+        description: Indicate the version of the Discovery API used to generate this doc.
         default: v1
       documentationLink:
         type: string
@@ -284,8 +260,7 @@ schemas:
         readOnly: true
       exponentialBackoffDefault:
         type: boolean
-        description: Enable exponential backoff for suitable methods in the generated
-          clients.
+        description: Enable exponential backoff for suitable methods in the generated clients.
       features:
         type: array
         description: A list of supported features for this API.
@@ -324,9 +299,7 @@ schemas:
         description: The name of this API.
       ownerDomain:
         type: string
-        description: The domain of the owner of this API. Together with the ownerName
-          and a packagePath values, this can be used to generate a library for this
-          API which would have a unique fully qualified name.
+        description: The domain of the owner of this API. Together with the ownerName and a packagePath values, this can be used to generate a library for this API which would have a unique fully qualified name.
       ownerName:
         type: string
         description: The name of the owner of this API. See ownerDomain.
@@ -348,8 +321,7 @@ schemas:
         description: The resources in this API.
         additionalProperties:
           "$ref": RestResource
-          description: An individual resource description. Contains methods and sub-resources
-            related to this resource.
+          description: An individual resource description. Contains methods and sub-resources related to this resource.
       revision:
         type: string
         description: The version of this API.
@@ -382,15 +354,13 @@ schemas:
         description: Description of this method.
       etagRequired:
         type: boolean
-        description: Whether this method requires an ETag to be specified. The ETag
-          is sent as an HTTP If-Match or If-None-Match header.
+        description: Whether this method requires an ETag to be specified. The ETag is sent as an HTTP If-Match or If-None-Match header.
       httpMethod:
         type: string
         description: HTTP method used by this method.
       id:
         type: string
-        description: A unique ID for this method. This property can be used to match
-          methods between different versions of Discovery.
+        description: A unique ID for this method. This property can be used to match methods between different versions of Discovery.
       mediaUpload:
         type: object
         description: Media upload parameters.
@@ -413,13 +383,11 @@ schemas:
                 properties:
                   multipart:
                     type: boolean
-                    description: True if this endpoint supports uploading multipart
-                      media.
+                    description: True if this endpoint supports uploading multipart media.
                     default: 'true'
                   path:
                     type: string
-                    description: The URI path to be used for upload. Should be used
-                      in conjunction with the basePath property at the api-level.
+                    description: The URI path to be used for upload. Should be used in conjunction with the basePath property at the api-level.
               simple:
                 type: object
                 description: Supports uploading as a single HTTP request.
@@ -430,13 +398,10 @@ schemas:
                     default: 'true'
                   path:
                     type: string
-                    description: The URI path to be used for upload. Should be used
-                      in conjunction with the basePath property at the api-level.
+                    description: The URI path to be used for upload. Should be used in conjunction with the basePath property at the api-level.
       parameterOrder:
         type: array
-        description: Ordered list of required parameters, serves as a hint to clients
-          on how to structure their method signatures. The array is ordered such that
-          the "most-significant" parameter appears first.
+        description: Ordered list of required parameters, serves as a hint to clients on how to structure their method signatures. The array is ordered such that the "most-significant" parameter appears first.
         items:
           type: string
       parameters:
@@ -447,8 +412,7 @@ schemas:
           description: Details for a single parameter in this method.
       path:
         type: string
-        description: The URI path of this REST method. Should be used in conjunction
-          with the basePath property at the api-level.
+        description: The URI path of this REST method. Should be used in conjunction with the basePath property at the api-level.
       request:
         type: object
         description: The schema for the request.
@@ -482,9 +446,7 @@ schemas:
         description: Whether this method supports subscriptions.
       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.
+        description: Indicates that downloads from this method should use the download service URL (i.e. "/download"). Only applies if the method supports media download.
   RestResource:
     id: RestResource
     type: object

data/lib/scorpio.rb

@@ -1,6 +1,19 @@
 require "scorpio/version"
+require "pathname"
+require "pp"
+require "api_hammer/ycomb"
+require "scorpio/json-schema-fragments"
 
 module Scorpio
+  def self.root
+    @root ||= Pathname.new(__FILE__).dirname.parent.expand_path
+  end
+
+  # generally put in code paths that are not expected to be valid control flow paths.
+  # rather a NotImplementedCorrectlyError. but that's too long.
+  class Bug < NotImplementedError
+  end
+
   proc { |v| define_singleton_method(:error_classes_by_status) { v } }.call({})
   class Error < StandardError; end
   class HTTPError < Error
@@ -53,13 +66,29 @@ module Scorpio
   error_classes_by_status.freeze
 
   autoload :Model, 'scorpio/model'
+  autoload :OpenAPI, 'scorpio/openapi'
+  autoload :Google, 'scorpio/google_api_document'
+  autoload :JSON, 'scorpio/json'
+  autoload :Schema, 'scorpio/schema'
 
   class << self
     def stringify_symbol_keys(hash)
       unless hash.is_a?(Hash)
-        raise ArgumentError, "expected argument to be a Hash; got #{hash.class}: #{hash.inspect}"
+        raise ArgumentError, "expected argument to be a Hash; got #{hash.class}: #{hash.pretty_inspect}"
       end
       hash.map { |k,v| {k.is_a?(Symbol) ? k.to_s : k => v} }.inject({}, &:update)
     end
   end
+
+  module FingerprintHash
+    def ==(other)
+      other.respond_to?(:fingerprint) && other.fingerprint == self.fingerprint
+    end
+
+    alias eql? ==
+
+    def hash
+      fingerprint.hash
+    end
+  end
 end

data/lib/scorpio/google_api_document.rb

@@ -0,0 +1,232 @@
+require 'api_hammer/ycomb'
+require 'scorpio/schema_object_base'
+
+module Scorpio
+  module Google
+    apidoc_schema_doc = ::JSON.parse(Scorpio.root.join('documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest').read)
+    api_document_class = proc do |*key|
+      Scorpio.class_for_schema(Scorpio::JSON::Node.new_by_type(apidoc_schema_doc, ['schemas', *key]))
+    end
+
+    # naming these is not strictly necessary, but is nice to have.
+    # generated: puts Scorpio::Google::ApiDocument.document['schemas'].select { |k,v| v['type'] == 'object' }.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = api_document_class.call('#{k}')" }
+    DirectoryList   = api_document_class.call('DirectoryList')
+    JsonSchema      = api_document_class.call('JsonSchema')
+    RestDescription = api_document_class.call('RestDescription')
+    RestMethod      = api_document_class.call('RestMethod')
+    RestResource    = api_document_class.call('RestResource')
+
+    # not generated
+    RestMethodRequest = api_document_class.call('RestMethod', 'properties', 'request')
+    RestMethodResponse = api_document_class.call('RestMethod', 'properties', 'response')
+
+    # 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
+        dup_doc = ::JSON.parse(::JSON.generate(object.content))
+        # openapi does not want an id field on schemas
+        dup_doc.delete('id')
+        if dup_doc['properties'].is_a?(Hash)
+          required_properties = dup_doc['properties'].select do |key, value|
+            value.is_a?(Hash) ? value.delete('required') : nil
+          end.keys
+          # 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
+        end
+        dup_doc
+      end
+    end
+    [JsonSchema, RestMethodRequest, RestMethodResponse].each { |klass| klass.send(:include, SchemaLike) }
+
+    class RestDescription
+      def to_openapi_document(options = {})
+        Scorpio::OpenAPI::Document.new(to_openapi_hash(options))
+      end
+
+      def to_openapi_hash(options = {})
+        # we will be modifying the api document (RestDescription). clone self and modify that one.
+        ad = self.class.new(::JSON.parse(::JSON.generate(object.document)))
+        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'] = []
+              #operation['summary'] = 
+              operation['description'] = method['description'] if method['description']
+              if method.resource_name && options[:x]
+                operation['x-resource'] = method.resource_name
+                operation['x-resource-method'] = method.method_name
+              end
+              #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.rootUrl).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'],
+          'paths' => paths, #/definitions/paths
+        }
+        if ad.schemas
+          openapi['definitions'] = ad.schemas
+          ad.schemas.each do |name, schema|
+            openapi = 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
+                      ycomb do |toopenapirec|
+                        proc do |toopenapiobject|
+                          toopenapiobject = toopenapiobject.to_openapi if toopenapiobject.respond_to?(:to_openapi)
+                          if toopenapiobject.respond_to?(:to_hash)
+                            toopenapiobject.map { |k, v| {toopenapirec.call(k) => toopenapirec.call(v)} }.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
+        end
+        # check we haven't got anything that shouldn't go in a openapi document
+        openapi = ycomb do |rec|
+          proc do |object|
+            object = object.to_openapi if object.respond_to?(:to_openapi)
+            if object.respond_to?(:to_hash)
+              object.map { |k, v| {rec.call(k) => rec.call(v)} }.inject({}, &:update)
+            elsif object.respond_to?(:to_ary)
+              object.map(&rec)
+            elsif object.is_a?(Symbol)
+              object.to_s
+            elsif [String, TrueClass, FalseClass, NilClass, Numeric].any? { |c| object.is_a?(c) }
+              object
+            else
+              raise(TypeError, "bad (not jsonifiable) object: #{object.pretty_inspect}")
+            end
+          end
+        end.call(openapi)
+      end
+    end
+  end
+end