scorpio 0.6.4 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4505d3bd4e9dc299b95b21ce5305e7864200fb0481be3f2600f75c3476f73d
-  data.tar.gz: 613abb854fffaf49a45f8c9e19a0f150f0fef9b7500e50cf20dc2a6f58023347
+  metadata.gz: 1f812bf2fd5370f04a99f7f4acfa20e731f91209a27bbec923b647620dba75e7
+  data.tar.gz: 4ba616f4cb7e42f5ac4ac82b04ec6f2c6ecb9ac7777e3efc275a620180ec0f37
 SHA512:
-  metadata.gz: 26cd883ee719f0e2683ac53c1be85d9296c90b92e80a799d938cf361c431ca486dd4e6a2db73539d7f133fa162fd104f85f4d9c9ec89b7f74e2187e8218b543b
-  data.tar.gz: 945afcb210c0b0ea8801393a3586b83045f82bcb94724021e3c69a6320ba32c23ddbeb6652644a6c3ea063830550f97e3001e661251662a8e6d976bc2cfdce62
+  metadata.gz: 70bd41fd5637305698660684e25d4cd3e3726aeb12faa17ffcf9ef7d04a0417ba271e01d85b6e2d95bbff08ee83951f6fb0542fbba6eb941a547a67f88aca34a
+  data.tar.gz: 7e61e67b208a251d88f838aaaa481498ce2e44797ea955ae3b31f6b3108a42e3c6e67a0e27765deed911d578770cfd9b2131b4b44f8164d40191c395c91e09a6

data/.yardopts

@@ -1 +1,6 @@
---main README.md --markup=markdown {lib}/**/*.rb
+--main README.md
+--markup=markdown
+--markup-provider=redcarpet
+--no-private
+--files pages/**/*.md
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# v0.7.0
+
+- OpenAPI v3.1 (OpenAPI::V3_1)
+- rename OpenAPI::V3 to OpenAPI::V3_0
+- OpenAPI::Reference resolves $ref across documents
+- Scorpio::Google::RestDescription is an API description document on its own; rm conversion to OpenAPI
+- JSI ~> v0.9
+
 # v0.6.4
 
 - JSI ~> v0.8.1
@@ -51,7 +59,7 @@
 - bugfixes
 
 # v0.4.0
-- Scorpio::OpenAPI v3 classes updated from OAI/OpenAPI-Specification branch oas3-schema
+- Scorpio::OpenAPI v3.0 classes updated from OAI/OpenAPI-Specification branch oas3-schema
 - any uniquely-named request parameter will have accessors on Request and can be passed as config to #initialize
 - Request#each_page_ur for pagination
 - significantly improved documentation
@@ -61,7 +69,7 @@
 - miscellaneous minor fixes and improvements
 
 # v0.3.0
-- OpenAPI v3 support
+- OpenAPI v3.0 support
 - classes Request/Response, OpenAPI::Operation, OpenAPI::Document handle a request. ResourceBase relies on these.
 - extract SchemaInstanceBase and friends to gem JSI
 

data/LICENSE.md

@@ -1,8 +1,6 @@
-Copright © [Ethan](https://github.com/notEthan/)
+Scorpio Copyright © [Ethan](https://github.com/notEthan/), licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 
-[<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).
+[<img align="right" src="https://www.gnu.org/graphics/agplv3-155x51.png">](https://www.gnu.org/licenses/agpl-3.0.html)
 
 GNU Affero General Public License
 =================================

data/README.md

@@ -1,26 +1,32 @@
 # Scorpio
 
-![Test CI Status](https://github.com/notEthan/scorpio/actions/workflows/test.yml/badge.svg?branch=stable)
+![Test CI Status](https://github.com/notEthan/scorpio/actions/workflows/test.yml/badge.svg?branch=main)
 [![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.
+Scorpio is a library that helps you, as a client, consume a service whose API is described by an OpenAPI description. You provide the OpenAPI description document, a little bit of configuration, and using that Scorpio will dynamically construct interfaces for you to call the service's operations and interact with its resources like an ORM.
 
-Note: The canonical location of this README is on [RubyDoc](http://rubydoc.info/gems/scorpio/). When viewed on [Github](https://github.com/notEthan/scorpio/), it may be inconsistent with the latest released gem, and Yardoc links will not work.
+Note: The canonical location of this README is on [RubyDoc](https://rubydoc.info/gems/scorpio/). When viewed on [Github](https://github.com/notEthan/scorpio/), it may be inconsistent with the latest released gem, and Yardoc links will not work.
 
 ## Background
 
-To start with, you need an OpenAPI (formerly known as Swagger) document describing a service you will be consuming. v2 and v3 are both supported.[^1] This document can be written by hand or sometimes generated from other existing sources. The creation of an OpenAPI document describing your service is outside the scope of Scorpio. Here are several resources on OpenAPI:
+### OpenAPI specification and OpenAPI documents
 
+To start with, you need an OpenAPI document (an OAD) describing a service you will be consuming. OpenAPI Specification v3.1, v3.0, and v2 (formerly known as Swagger) are supported. An OAD can be written by hand or sometimes generated from other existing sources. The creation of an OpenAPI document describing a given service is outside the scope of Scorpio. Here are several resources on OpenAPI:
+
+- [Learn about OpenAPI](https://learn.openapis.org/)
 - [OpenAPI Specification at Wikipedia](https://en.wikipedia.org/wiki/OpenAPI_Specification)
-- [OpenAPI Initiative](https://www.openapis.org/) is the official web site for OpenAPI
-- [OpenAPI Specification on GitHub](https://github.com/OAI/OpenAPI-Specification)
-- [swagger.io](https://swagger.io/) API tooling
+- OpenAPI Specifications [v3.1](https://spec.openapis.org/oas/v3.1.html), [v3.0](https://spec.openapis.org/oas/v3.0.html), [v2.0](https://spec.openapis.org/oas/v2.0.html)
+- [OpenAPI Specification development on GitHub](https://github.com/OAI/OpenAPI-Specification)
+
+### JSON Schema, JSI
+
+[JSON Schema](https://json-schema.org/) is an important part of OpenAPI documents, in which it is used to describe various components of a service's requests and responses.
 
-OpenAPI relies on the definition of schemas using the JSON schema specification, which can be learned about at https://json-schema.org/
+[JSI](https://github.com/notEthan/jsi) is a Ruby library that offers an Object-Oriented representation for JSON data using JSON Schemas.
 
-Once you have the OpenAPI document describing the service you will consume, you can get started implementing the code that will interact with that service.
+Scorpio utilizes JSI to instantiate components of the API described by JSON schemas, in particular JSON request and response bodies.
 
-[^1]: Certain features may be missing, but Scorpio tries to make workarounds easy. Issues and pull requests regarding missing functionality are welcome.
+Scorpio's core is built on JSI. It uses the JSON Schema describing OpenAPI documents (which is published along with the OpenAPI specification) with JSI to instantiate an OAD and to define functionality of the document, operations, and other components.
 
 ## Pet Store (using Scorpio::ResourceBase)
 
@@ -33,38 +39,46 @@ require 'scorpio'
 # PetStore is a module to contain our pet store related classes.
 # it is optional - your naming conventions are your own.
 module PetStore
-  # Scorpio's recommended structure is to have a base class which inherits from
-  # Scorpio::ResourceBase to represent the Pet Store and all its resources.
+  # Scorpio's recommended structure is to have a base class which
+  # inherits from Scorpio::ResourceBase to represent the Pet Store
+  # and all its resources.
   #
-  # you configure the openapi document and other shared configuration on this class.
+  # You configure the OpenAPI document and other shared configuration
+  # on this class.
   class Resource < Scorpio::ResourceBase
-    # set the openapi document. you'll usually want this to be a file in your local filesystem
-    # (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('https://petstore.swagger.io/v2/swagger.json').body)
+    # Set the OpenAPI document. You'll usually want this to be a file in
+    # your local filesystem (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.
+    self.openapi_document = JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body, freeze: true)
   end
 
-  # a Pet is a resource of the pet store, so inherits from PetStore::Resource
+  # a Pet is a resource of the pet store, so inherits from
+  # PetStore::Resource
   class Pet < Resource
-    # setting the tag name tells Scorpio to associate operations tagged with 'pet' with this
-    # class and its instances. this lets you call operations such as addPet, updatePet, etc.
+    # Setting the tag name tells Scorpio to associate operations tagged
+    # with 'pet' with this class and its instances. This lets you call
+    # operations such as addPet, updatePet, etc.
     self.tag_name = 'pet'
 
-    # setting the schemas which represent a Pet will let scorpio return results from operation
-    # calls properly instantiated as Pet instances. for example, calling getPetById will return
-    # a PetStore::Pet instance since its success response refers to #/definitions/Pet.
+    # Setting the schemas which represent a Pet will let Scorpio
+    # return results from operation calls properly instantiated as
+    # Pet instances. For example, calling getPetById will return a
+    # PetStore::Pet instance since its success response refers
+    # to #/definitions/Pet.
     #
-    # this works for nested structures as well, e.g. findPetsByStatus returns an array of
-    # #/definitions/Pet and likewise Scorpio will return an array of PetStore::Pet instances.
+    # This works for nested structures as well, e.g. findPetsByStatus
+    # returns an array of #/definitions/Pet and likewise Scorpio will
+    # return an array of PetStore::Pet instances.
     #
-    # this also adds accessors for properties of the schema - in this case #id, #name, #tags, etc.
+    # This also adds accessors for properties of the schema - in this
+    # case #id, #name, #tags, etc.
     self.represented_schemas = [openapi_document.definitions['Pet']]
   end
 end
 ```
 
-That should be all you need to start calling operations:
+That is all you need to start calling operations:
 
 ```ruby
 # call the operation findPetsByStatus
@@ -73,6 +87,7 @@ sold_pets = PetStore::Pet.findPetsByStatus(status: 'sold')
 # sold_pets is an array-like collection of PetStore::Pet instances
 
 pet = sold_pets.sample
+# => #<PetStore::Pet #{<JSI> "id" => 9, "name" => "Ix", "status" => "sold", ...}>
 
 pet.tags.map(&:name)
 # note that you have accessors on PetStore::Pet like #tags, and also that
@@ -87,9 +102,10 @@ pet == PetStore::Pet.getPetById(petId: pet['id'])
 # let's name the pet after ourself
 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.
+# 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: https://petstore.swagger.io/#/pet/updatePet
 pet.updatePet
 
@@ -106,23 +122,25 @@ PetStore::Pet.getPetById(petId: 0)
 
 Isn't that cool? You get class methods like getPetById, instance methods like updatePet, attribute accessors like #name and #tags, all dynamically generated from the OpenAPI description. You just make a few classes with a line or two of configuration in each.
 
-## Pet Store (using Scorpio::OpenAPI classes)
+## Pet Store (without Scorpio::ResourceBase)
 
-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.
+You do not have to define resource classes as above to use Scorpio to interact with a service - ResourceBase is a helpful representation of the service's resources, but operations can be run directly from Scorpio's representation of the OpenAPI document.
 
-We start by instantiating the OpenAPI document. `Scorpio::OpenAPI::Document.from_instance` returns a V2 or V3 OpenAPI Document class instance.
+This representation uses [JSI](https://github.com/notEthan/jsi) with the JSON schema describing OpenAPI documents (for the relevant version of the OpenAPI specification). Scorpio's API client functionality is implemented using these schemas, and the result is that the instantiated OpenAPI document is itself the client to the service it describes.
+
+To consume the Pet Store service, we start by instantiating the OpenAPI document. {Scorpio.new_document} returns a JSI instance described by the appropriate OpenAPI document schema.
 
 ```ruby
 require 'scorpio'
-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", ...}
+pet_store_content = JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body, freeze: true)
+pet_store_oad = Scorpio::OpenAPI::Document.from_instance(pet_store_content)
+# => #{<JSI (Scorpio::OpenAPI::V2::Document)> "swagger" => "2.0", ...}
 ```
 
-The OpenAPI document holds the JSON that represents it, so to get an Operation you go through the document's paths, just as it is represented in the JSON.
+Within `pet_store_oad` we can access an operation under the OAD's `#paths` property - JSI objects have accessors for described properties, or can be subscripted as with the Hash/Array nodes they represent.
 
 ```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']
+inventory_op = pet_store_oad.paths['/store/inventory']['get']
 # => #{<JSI (Scorpio::OpenAPI::V2::Operation)>
 #      "summary" => "Returns pet inventories by status",
 #      "operationId" => "getInventory",
@@ -130,14 +148,14 @@ inventory_op = pet_store_doc.paths['/store/inventory']['get']
 #    }
 ```
 
-Alternatively, Scorpio defines a helper `Document#operations` which behaves like an Enumerable of all the Operations in the Document. It can be subscripted with the `operationId`:
+Alternatively, Scorpio defines a helper {Scorpio::OpenAPI::Document#operations} which is an Enumerable of all the Operations in the Document. It can be subscripted with an `operationId`:
 
 ```ruby
-inventory_op = pet_store_doc.operations['getInventory']
+inventory_op = pet_store_oad.operations['getInventory']
 # => returns the same inventory_op as above.
 ```
 
-Now that we have an operation, we can run requests from it. {Scorpio::OpenAPI::Operation#run} performs the operation by running a request. If the response is an error, a {Scorpio::HTTPError} subclass will be raised. On success, it returns the response body entity, instantiated according to the OpenAPI schema for the operation response, if specified. For more detail on how json-schema instances are represented, see the gem [JSI](https://github.com/notEthan/jsi).
+Now that we have an operation, we can run requests from it with {Scorpio::OpenAPI::Operation#run}. On success, it returns the parsed response body, instantiated using the JSON schema for the operation response, if that is specified in the OAD.
 
 ```ruby
 inventory = inventory_op.run
@@ -150,25 +168,29 @@ 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:
+We'll pick a state, find a pet, and go through the rest of the example in the ResourceBase section pretty much like it is up there:
 
 ```ruby
 # 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
+# we will be mutating one of these, so we pass mutable: true
+sold_pets = pet_store_oad.operations['findPetsByStatus'].run(status: 'sold', mutable: true)
+# sold_pets is an array-like collection of JSI instances.
+# Each item is described by the OAD's Pet schema.
+sold_pets.first.described_by?(pet_store_oad.definitions['Pet']) # => true
 
 pet = sold_pets.detect { |pet| pet.tags.any? }
 
 pet.tags.map(&:name)
-# 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)
+# 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 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'])
+pet_by_id = pet_store_oad.operations['getPetById'].run(petId: pet['id'])
 
 # unlike ResourceBase instances above, JSI instances have stricter
 # equality and the pets returned from different operations are not
@@ -181,14 +203,14 @@ pet.name = ENV['USER']
 
 # store the result in the pet store.
 # updatePet: https://petstore.swagger.io/#/pet/updatePet
-pet_store_doc.operations['updatePet'].run(body_object: pet)
+pet_store_oad.operations['updatePet'].run(body_object: pet)
 
 # check that it was saved
-pet_store_doc.operations['getPetById'].run(petId: pet['id']).name
+pet_store_oad.operations['getPetById'].run(petId: pet['id']).name
 # => "ethan" (unless for some reason your name is not Ethan)
 
 # here is how errors are handled:
-pet_store_doc.operations['getPetById'].run(petId: 0)
+pet_store_oad.operations['getPetById'].run(petId: 0)
 # raises: Scorpio::HTTPErrors::NotFound404Error
 #   Error calling operation getPetById:
 #   {"code":1,"type":"error","message":"Pet not found"}
@@ -198,7 +220,7 @@ pet_store_doc.operations['getPetById'].run(petId: 0)
 
 For another example of an API that a client interacts with using Scorpio::ResourceBase, Scorpio's tests implement the Blog service. This is defined in test/blog.rb. The service uses ActiveRecord models and Sinatra to make a simple RESTful service.
 
-Its API is described in `test/blog.openapi.yml`, defining the Article resource, several operations, and schemas. The client is set up in `test/blog_scorpio_models.rb`. The base class BlogModel defines the base_url and the api description, as well as some other optional setup done for testing. Its operations are tested in `test/scorpio_test.rb`.
+Its API is described in `test/blog.openapi<version>.yml`, defining the Article resource, several operations, and schemas. The client is set up in `test/blog_scorpio_models.rb`. The base class BlogModel defines the base_url and the api description, as well as some other optional setup done for testing. Its operations are tested in `test/scorpio_test.rb`.
 
 ## Scorpio::ResourceBase
 
@@ -222,12 +244,12 @@ When these are set, Scorpio::ResourceBase looks through the API description and
 
 ## Scorpio::Ur
 
-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:
+If you need a more complete representation of the HTTP request and/or response, {Scorpio::OpenAPI::Operation#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 (without Scorpio::ResourceBase)", this code will return an Ur:
 
 ```ruby
-inventory_op = Scorpio::OpenAPI::Document.from_instance(JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body)).paths['/store/inventory']['get']
+inventory_op = Scorpio.new_document(JSON.parse(Faraday.get('https://petstore.swagger.io/v2/swagger.json').body, freeze: true)).paths['/store/inventory']['get']
 inventory_ur = inventory_op.run_ur
-# => #{<Scorpio::Ur fragment="#"> ...}
+# => #{<JSI (Ur + Scorpio::Ur)> "bound" => "outbound", "request" => ...}
 ```
 
 ### Scorpio ResourceBase pickle adapter
@@ -236,24 +258,16 @@ Scorpio provides a pickle adapter to use models with [Pickle](https://rubygems.o
 
 ### Google API discovery service
 
-An initial implementation of Scorpio::ResourceBase was based on the format defined for Google's API discovery service.
+Scorpio was initially built to work with the API description format defined for Google's API discovery service. Though Scorpio is now primarily built for OpenAPI, Google's format is still supported.
 
 For background on the Google discovery service and the API description format it defines, see:
 
 - https://developers.google.com/discovery/
 - https://developers.google.com/discovery/v1/reference/
 
-This format is still supported indirectly, by converting from a Google API document to OpenAPI using `Scorpio::Google::RestDescription#to_openapi_document`. Example conversion looks like:
-
-```ruby
-class MyModel < Scorpio::ResourceBase
-  rest_description_doc = YAML.load_file('path/to/doc.yml')
-  rest_description = Scorpio::Google::RestDescription.new(rest_description_doc)
-  self.openapi_document = rest_description.to_openapi_document
+Such an API description (called a "rest description" or sometimes "discovery document") is an instance of {Scorpio::Google::RestDescription}. Note that Scorpio being OpenAPI-centric, some interfaces use the idioms or terminology of OpenAPI, e.g. a {Scorpio::Google::RestMethod} uses the interface of {Scorpio::OpenAPI::Operation}. See `examples/google` in Scorpio's repository for example usage.
 
-  # ... the remainder of your setup and model code here
-end
-```
+Google does provide official [API clients in Ruby](https://github.com/googleapis/google-api-ruby-client). These weigh in at nearly 5 million lines of code across about 500 gems, almost all generated code from the same API documents Scorpio uses. Scorpio's dynamic handling of API documents and their schemas provides comparable functionality.
 
 ## Other