scorpio 0.4.5 → 0.6.0

data/README.md

@@ -1,6 +1,6 @@
 # Scorpio
 
-[![Build Status](https://travis-ci.org/notEthan/scorpio.svg?branch=master)](https://travis-ci.org/notEthan/scorpio)
+![Test CI Status](https://github.com/notEthan/scorpio/actions/workflows/test.yml/badge.svg?branch=stable)
 [![Coverage Status](https://coveralls.io/repos/github/notEthan/scorpio/badge.svg)](https://coveralls.io/github/notEthan/scorpio)
 
 Scorpio is a library that helps you, as a client, consume an HTTP service described by an OpenAPI document. You provide the OpenAPI description document, a little bit of configuration, and Scorpio will take that and dynamically generate an interface for you to call the service's operations and interact with its resources as an ORM.
@@ -24,7 +24,7 @@ Once you have the OpenAPI document describing the service you will consume, you
 
 ## Pet Store (using Scorpio::ResourceBase)
 
-Let's dive into some code, shall we? If you have learned about OpenAPI, you likely learned using the example of the Pet Store service. This README will use the same service. Its documentation is at http://petstore.swagger.io/.
+Let's dive into some code, shall we? If you have learned about OpenAPI, you likely learned using the example of the Pet Store service. This README will use the same service. Its documentation is at https://petstore.swagger.io/.
 
 Using the OpenAPI document, we can start interacting with the pet store with very little code. Here is that code, with explanations of each part in the comments.
 
@@ -42,7 +42,7 @@ module PetStore
     # (making network calls at application boot time is usually a bad idea), but for this
     # example we will do a quick-and-dirty http get.
     require 'json'
-    self.openapi_document = JSON.parse(Faraday.get('http://petstore.swagger.io/v2/swagger.json').body)
+    self.openapi_document = JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body)
   end
 
   # a Pet is a resource of the pet store, so inherits from PetStore::Resource
@@ -67,7 +67,8 @@ end
 That should be all you need to start calling operations:
 
 ```ruby
-# call the operation findPetsByStatus: http://petstore.swagger.io/#/pet/findPetsByStatus
+# call the operation findPetsByStatus
+# doc: https://petstore.swagger.io/#/pet/findPetsByStatus
 sold_pets = PetStore::Pet.findPetsByStatus(status: 'sold')
 # sold_pets is an array-like collection of PetStore::Pet instances
 
@@ -79,7 +80,7 @@ pet.tags.map(&:name)
 # (your tag names will be different depending on what's in the pet store)
 # => ["aucune"]
 
-# compare to getPetById: http://petstore.swagger.io/#/pet/getPetById
+# compare to getPetById: https://petstore.swagger.io/#/pet/getPetById
 pet == PetStore::Pet.getPetById(petId: pet['id'])
 # pet is the same, retrieved using the getPetById operation
 
@@ -89,7 +90,7 @@ pet.name = ENV['USER']
 # store the result in the pet store. note the updatePet call from the instance - our
 # calls so far have been on the class PetStore::Pet, but scorpio defines instance
 # methods to call operations where appropriate as well.
-# updatePet: http://petstore.swagger.io/#/pet/updatePet
+# updatePet: https://petstore.swagger.io/#/pet/updatePet
 pet.updatePet
 
 # check that it was saved
@@ -107,13 +108,13 @@ Isn't that cool? You get class methods like getPetById, instance methods like up
 
 ## Pet Store (using Scorpio::OpenAPI classes)
 
-You do not have to define resource classes to use Scorpio to call OpenAPI operations - the classes Scorpio uses to represent concepts from OpenAPI can be called directly. Scorpio uses [JSI](https://github.com/notEthan/ur) classes to represent OpenAPI schemes such as the Document and its Operations.
+You do not have to define resource classes to use Scorpio to call OpenAPI operations - the classes Scorpio uses to represent concepts from OpenAPI can be called directly. Scorpio uses [JSI](https://github.com/notEthan/jsi) classes to represent OpenAPI schemes such as the Document and its Operations.
 
 We start by instantiating the OpenAPI document. `Scorpio::OpenAPI::Document.from_instance` returns a V2 or V3 OpenAPI Document class instance.
 
 ```ruby
 require 'scorpio'
-pet_store_doc = Scorpio::OpenAPI::Document.from_instance(JSON.parse(Faraday.get('http://petstore.swagger.io/v2/swagger.json').body))
+pet_store_doc = Scorpio::OpenAPI::Document.from_instance(JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body))
 # => #{<Scorpio::OpenAPI::V2::Document fragment="#"> "swagger" => "2.0", ...}
 ```
 
@@ -122,7 +123,7 @@ The OpenAPI document holds the JSON that represents it, so to get an Operation y
 ```ruby
 # the store inventory operation will let us see what statuses there are in the store.
 inventory_op = pet_store_doc.paths['/store/inventory']['get']
-# => #{<Scorpio::OpenAPI::V2::Operation fragment="#/paths/~1store~1inventory/get">
+# => #{<JSI (Scorpio::OpenAPI::V2::Operation)>
 #      "summary" => "Returns pet inventories by status",
 #      "operationId" => "getInventory",
 #      ...
@@ -140,7 +141,7 @@ Now that we have an operation, we can run requests from it. {Scorpio::OpenAPI::O
 
 ```ruby
 inventory = inventory_op.run
-# => #{<JSI::SchemaClasses["dde3#/paths/~1store~1inventory/get/responses/200/schema"] fragment="#">
+# => #{<JSI>
 #      "unavailable" => 4,
 #      "unloved - needs a home" => 1,
 #      "available" => 2350,
@@ -152,28 +153,36 @@ inventory = inventory_op.run
 let's pick a state and find a pet. we'll go through the rest of the example in the ResourceBase section pretty much like it is up there:
 
 ```ruby
-# call the operation findPetsByStatus: http://petstore.swagger.io/#/pet/findPetsByStatus
+# call the operation findPetsByStatus
+# doc: https://petstore.swagger.io/#/pet/findPetsByStatus
 sold_pets = pet_store_doc.operations['findPetsByStatus'].run(status: 'sold')
 # sold_pets is an array-like collection of JSI instances
 
 pet = sold_pets.detect { |pet| pet.tags.any? }
 
 pet.tags.map(&:name)
-# note that you have accessors on PetStore::Pet like #tags, and also that
+# note that you have accessors on the returned JSI like #tags, and also that
 # tags have accessors for properties 'name' and 'id' from the tags schema
 # (your tag names will be different depending on what's in the pet store)
 # => ["aucune"]
 
-# compare to getPetById: http://petstore.swagger.io/#/pet/getPetById
-pet == pet_store_doc.operations['getPetById'].run(petId: pet['id'])
+# compare the pet from findPetsByStatus to one returned from getPetById
+# doc: https://petstore.swagger.io/#/pet/getPetById
+pet_by_id = pet_store_doc.operations['getPetById'].run(petId: pet['id'])
+
+# unlike ResourceBase instances above, JSI instances have stricter
+# equality and the pets returned from different operations are not
+# equal, though the underlying JSON instance is.
+pet_by_id == pet
 # => false
-# without ResourceBase, pet is not considered to be the same compared with getPetById [TODO may change in jsi]
+pet_by_id.jsi_instance == pet.jsi_instance
+# => true
 
 # let's name the pet after ourself
 pet.name = ENV['USER']
 
 # store the result in the pet store.
-# updatePet: http://petstore.swagger.io/#/pet/updatePet
+# updatePet: https://petstore.swagger.io/#/pet/updatePet
 pet_store_doc.operations['updatePet'].run(body_object: pet)
 
 # check that it was saved
@@ -218,7 +227,7 @@ When these are set, Scorpio::ResourceBase looks through the API description and
 If you need a more complete representation of the HTTP request and/or response, Scorpio::OpenAPI::Operation#run_ur or Scorpio::Request#run_ur will return a representation of the request and response defined by the gem [Ur](https://github.com/notEthan/ur). See that link for more detail. Relating to the example above titled "Pet Store (using Scorpio::OpenAPI classes)", this code will return an Ur:
 
 ```ruby
-inventory_op = Scorpio::OpenAPI::Document.from_instance(JSON.parse(Faraday.get('http://petstore.swagger.io/v2/swagger.json').body)).paths['/store/inventory']['get']
+inventory_op = Scorpio::OpenAPI::Document.from_instance(JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body)).paths['/store/inventory']['get']
 inventory_ur = inventory_op.run_ur
 # => #{<Scorpio::Ur fragment="#"> ...}
 ```
@@ -260,4 +269,8 @@ The detailed, machine-interpretable description of an API provided by a properly
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+[<img align="right" src="https://github.com/notEthan/scorpio/raw/master/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
+
+Scorpio is licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
+
+Unlike the MIT or BSD licenses more commonly used with Ruby gems, this license requires that if you modify Scorpio and propagate your changes, e.g. by including it in a web application, your modified version must be publicly available. The common path of forking on Github should satisfy this requirement.

data/documents/github.com/OAI/OpenAPI-Specification/blob/oas3-schema/schemas/v3.0/schema.yaml

@@ -40,6 +40,14 @@ definitions:
       '^\$ref$':
         type: string
         format: uri-reference
+  SchemaReference:
+    type: object
+    required:
+      - $ref
+    patternProperties:
+      '^\$ref$':
+        type: string
+        format: uri-reference
   Info:
     type: object
     required:
@@ -135,7 +143,7 @@ definitions:
         patternProperties:
           '^[a-zA-Z0-9\.\-_]+$':
             oneOf:
-              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/SchemaReference'
               - $ref: '#/definitions/Schema'
       responses:
         type: object
@@ -266,39 +274,39 @@ definitions:
       not:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       allOf:
         type: array
         items:
           oneOf:
             - $ref: '#/definitions/Schema'
-            - $ref: '#/definitions/Reference'
+            - $ref: '#/definitions/SchemaReference'
       oneOf:
         type: array
         items:
           oneOf:
             - $ref: '#/definitions/Schema'
-            - $ref: '#/definitions/Reference'
+            - $ref: '#/definitions/SchemaReference'
       anyOf:
         type: array
         items:
           oneOf:
             - $ref: '#/definitions/Schema'
-            - $ref: '#/definitions/Reference'
+            - $ref: '#/definitions/SchemaReference'
       items:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       properties:
         type: object
         additionalProperties:
           oneOf:
             - $ref: '#/definitions/Schema'
-            - $ref: '#/definitions/Reference'
+            - $ref: '#/definitions/SchemaReference'
       additionalProperties:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
           - type: boolean
         default: true
       description:
@@ -399,7 +407,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       example: {}
       encoding:
         type: object
@@ -417,7 +425,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       examples:
         type: object
         additionalProperties:
@@ -486,7 +494,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       example: {}
     patternProperties:
       '^x-': {}
@@ -522,7 +530,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       examples:
         type: object
         additionalProperties:
@@ -769,7 +777,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       example: {}
     patternProperties:
       '^x-': {}
@@ -815,7 +823,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       example: {}
     patternProperties:
       '^x-': {}
@@ -858,7 +866,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       example: {}
     patternProperties:
       '^x-': {}
@@ -901,7 +909,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       example: {}
     patternProperties:
       '^x-': {}
@@ -956,13 +964,13 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       examples:
         type: object
         additionalProperties:
           oneOf:
             - $ref: '#/definitions/Example'
-            - $ref: '#/definitions/Reference'
+            - $ref: '#/definitions/SchemaReference'
     patternProperties:
       '^x-': {}
     additionalProperties: false
@@ -1008,13 +1016,13 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       examples:
         type: object
         additionalProperties:
           oneOf:
             - $ref: '#/definitions/Example'
-            - $ref: '#/definitions/Reference'
+            - $ref: '#/definitions/SchemaReference'
     patternProperties:
       '^x-': {}
     additionalProperties: false    
@@ -1057,7 +1065,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       examples:
         type: object
         additionalProperties:
@@ -1106,7 +1114,7 @@ definitions:
       schema:
         oneOf:
           - $ref: '#/definitions/Schema'
-          - $ref: '#/definitions/Reference'
+          - $ref: '#/definitions/SchemaReference'
       examples:
         type: object
         additionalProperties:

data/lib/scorpio/google_api_document.rb

@@ -1,19 +1,30 @@
+# frozen_string_literal: true
+
 module Scorpio
   module Google
-    discovery_rest_description_doc = JSI::JSON::Node.new_doc(::JSON.parse(Scorpio.root.join('documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest').read))
-
-    discovery_metaschema = discovery_rest_description_doc['schemas']['JsonSchema']
-    rest_description_schema = JSI.class_for_schema(discovery_metaschema).new(discovery_rest_description_doc['schemas']['RestDescription'])
-    discovery_rest_description = JSI.class_for_schema(rest_description_schema).new(discovery_rest_description_doc)
+    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,
+      metaschema_root_ptr: JSI::Ptr['schemas']['JsonSchema'],
+      root_schema_ptr: JSI::Ptr['schemas']['RestDescription'],
+      metaschema_instance_modules: [JSI::Schema::Draft04],
+    )
 
     # naming these is not strictly necessary, but is nice to have.
-    DirectoryList      = JSI.class_for_schema(discovery_rest_description['schemas']['DirectoryList'])
-    JsonSchema         = JSI.class_for_schema(discovery_rest_description['schemas']['JsonSchema'])
-    RestDescription    = JSI.class_for_schema(discovery_rest_description['schemas']['RestDescription'])
-    RestMethod         = JSI.class_for_schema(discovery_rest_description['schemas']['RestMethod'])
-    RestResource       = JSI.class_for_schema(discovery_rest_description['schemas']['RestResource'])
-    RestMethodRequest  = JSI.class_for_schema(discovery_rest_description['schemas']['RestMethod']['properties']['request'])
-    RestMethodResponse = JSI.class_for_schema(discovery_rest_description['schemas']['RestMethod']['properties']['response'])
+    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']
+    end
+
+    module RestMethod
+      Request = properties['request']
+      Response = properties['response']
+    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
@@ -36,16 +47,16 @@ module Scorpio
         dup_doc
       end
     end
-    [JsonSchema, RestMethodRequest, RestMethodResponse].each { |klass| klass.send(:include, SchemaLike) }
+    [JsonSchema, RestMethod::Request, RestMethod::Response].each { |m| m.send(:include, SchemaLike) }
 
-    class RestDescription
+    module RestDescription
       def to_openapi_document(options = {})
         Scorpio::OpenAPI::Document.from_instance(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(JSI::Typelike.as_json(instance))
+        ad = self.class.new(JSI::Typelike.as_json(self))
         ad_methods = []
         if ad['methods']
           ad_methods += ad['methods'].map do |mn, m|
@@ -161,6 +172,7 @@ module Scorpio
           '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

data/lib/scorpio/openapi/document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     # A document that defines or describes an API.
@@ -18,9 +20,9 @@ module Scorpio
             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(instance)
+              instance = Scorpio::OpenAPI::V2::Document.new_jsi(instance)
             elsif instance['openapi'] =~ /\A3(\.|\z)/
-              instance = Scorpio::OpenAPI::V3::Document.new(instance)
+              instance = Scorpio::OpenAPI::V3::Document.new_jsi(instance)
             else
               raise(ArgumentError, "instance does not look like a recognized openapi document")
             end
@@ -52,7 +54,7 @@ module Scorpio
         attr_writer :faraday_adapter
         def faraday_adapter
           return @faraday_adapter if instance_variable_defined?(:@faraday_adapter)
-          [Faraday.default_adapter]
+          [Faraday.default_adapter].freeze
         end
 
         attr_writer :logger
@@ -83,7 +85,7 @@ module Scorpio
       # 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
-      class Document
+      module Document
         module Configurables
           def scheme
             nil
@@ -126,7 +128,7 @@ module Scorpio
       # 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.
-      class Document
+      module Document
         module Configurables
           attr_writer :scheme
           def scheme
@@ -157,7 +159,7 @@ module Scorpio
                 scheme: scheme,
                 host: host,
                 path: basePath,
-              ).to_s
+              ).freeze
             end
           end