scorpio 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ef095c64774f95040582a9945d63cb2e58685403b66d49a9df1ec8976c5d12b
-  data.tar.gz: 777af82e020ab367e4280f10995b0aa84648782a157bc925529132c79e0b57d6
+  metadata.gz: b089f79e383e48c4d73793ceb0b1f3a3a254aca6abc34176252d24828ca0a9d8
+  data.tar.gz: aa9f34563eacae7e07c68f757a66bc53504dbdde741c285f40b34f15a64a08a4
 SHA512:
-  metadata.gz: 10fc95d393931ac8931c16bbe12dd62366e73480dc7ac5fa7c38efe8ab21cf49506eb659b0734bc3848df1a4994795adb6eb15302c3e3d942051ebe74f92dc09
-  data.tar.gz: e1ebe65228ca3412b24fedf99d0fbf84cd46acea560d09b32fc54a6142308fbfa088b471e65a0128b0ebffa1b1b4f5a3143be8c7f5b823a8c19c1d02eaaf5054
+  metadata.gz: 3d87134df5c11b0157c861fddd25947d3f45cbd2b17c29d9de23d22e8dd70e4edc2b6b1378ef3f5cfee0e0bff7872e9179e76b5f97e824d14a231ef19fd068cd
+  data.tar.gz: f82dd97cdb8a8b2f0912d1d5e9a8198f5f7734dcb46c914b0c9cb25a3763d0c0a9d4c0c690a3598d53a8c62f065fde18dec0c42586f2257da289b776d091a3c2

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# v0.6.0
+- ResourceBase resources in responses may be contained anywhere in the response object contained in ResourceBase::Container
+- ResourceBase defines class methods for operations whose request or response schemas are represented by the resource
+- JSI v0.6.0
+
 # v0.5.0
 - JSI schema classes change to schema modules, JSI instances may have multiple schemas (JSI v0.4, Ur v0.2)
 

data/LICENSE.md

@@ -2,7 +2,7 @@ Copright © [Ethan](https://github.com/notEthan/)
 
 [<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 Open Source Software licensed under the terms of the [GNU Affero General Public License version 3](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).
 
 GNU Affero General Public License
 =================================

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="#"> ...}
 ```

data/lib/scorpio/google_api_document.rb

@@ -1,7 +1,14 @@
+# frozen_string_literal: true
+
 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, metaschema_root_ptr: JSI::JSON::Pointer['schemas']['JsonSchema'], root_schema_ptr: JSI::JSON::Pointer['schemas']['RestDescription'])
+    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 = discovery_rest_description.schemas['DirectoryList'].jsi_schema_module
@@ -165,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.
@@ -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
@@ -157,7 +159,7 @@ module Scorpio
                 scheme: scheme,
                 host: host,
                 path: basePath,
-              ).to_s
+              ).freeze
             end
           end
 

data/lib/scorpio/openapi/operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     # An OpenAPI operation
@@ -43,37 +45,42 @@ module Scorpio
       end
       include Configurables
 
-      # @return [Boolean] v3?
+      # openapi v3?
+      # @return [Boolean]
       def v3?
         is_a?(V3::Operation)
       end
 
-      # @return [Boolean] v2?
+      # openapi v2?
+      # @return [Boolean]
       def v2?
         is_a?(V2::Operation)
       end
 
-      # @return [Scorpio::OpenAPI::Document] the document whence this operation came
+      # the document whence this operation came
+      # @return [Scorpio::OpenAPI::Document]
       def openapi_document
-        parent_jsis.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
+        jsi_parent_nodes.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
       end
 
+      # @return [String]
       def path_template_str
         return @path_template_str if instance_variable_defined?(:@path_template_str)
-        raise(Bug) unless parent_jsi.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent_jsi.is_a?(Scorpio::OpenAPI::V3::PathItem)
-        raise(Bug) unless parent_jsi.parent_jsi.is_a?(Scorpio::OpenAPI::V2::Paths) || parent_jsi.parent_jsi.is_a?(Scorpio::OpenAPI::V3::Paths)
-        @path_template_str = parent_jsi.jsi_ptr.reference_tokens.last
+        raise(Bug) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::PathItem) || jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        raise(Bug) unless jsi_parent_node.jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::Paths) || jsi_parent_node.jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::Paths)
+        @path_template_str = jsi_parent_node.jsi_ptr.tokens.last
       end
 
-      # @return [Addressable::Template] the path as an Addressable::Template
+      # the path as an Addressable::Template
+      # @return [Addressable::Template]
       def path_template
         return @path_template if instance_variable_defined?(:@path_template)
         @path_template = Addressable::Template.new(path_template_str)
       end
 
+      # the URI template, consisting of the base_url concatenated with the path template
       # @param base_url [#to_str] the base URL to which the path template is appended
-      # @return [Addressable::Template] the URI template, consisting of the base_url
-      #   concatenated with the path template
+      # @return [Addressable::Template]
       def uri_template(base_url: self.base_url)
         unless base_url
           raise(ArgumentError, "no base_url has been specified for operation #{self}")
@@ -83,33 +90,38 @@ module Scorpio
         Addressable::Template.new(File.join(base_url, path_template_str))
       end
 
-      # @return the HTTP method of this operation as indicated by the attribute name
-      #   for this operation from the parent PathItem
+      # the HTTP method of this operation as indicated by the attribute name for this operation
+      # from the parent PathItem
+      # @return [String]
       def http_method
         return @http_method if instance_variable_defined?(:@http_method)
-        raise(Bug) unless parent_jsi.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent_jsi.is_a?(Scorpio::OpenAPI::V3::PathItem)
-        @http_method = jsi_ptr.reference_tokens.last
+        raise(Bug) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::PathItem) || jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        @http_method = jsi_ptr.tokens.last
       end
 
-      # @return [String] a short identifier for this operation appropriate for an error message
+      # a short identifier for this operation appropriate for an error message
+      # @return [String]
       def human_id
         operationId || "path: #{path_template_str}, method: #{http_method}"
       end
 
+      # @param status [String, Integer]
       # @return [Scorpio::OpenAPI::V3::Response, Scorpio::OpenAPI::V2::Response]
       def oa_response(status: )
         status = status.to_s if status.is_a?(Numeric)
-        if self.responses
-          _, oa_response = self.responses.detect { |k, v| k.to_s == status }
-          oa_response ||= self.responses['default']
+        if responses
+          _, oa_response = responses.detect { |k, v| k.to_s == status }
+          oa_response ||= responses['default']
         end
         oa_response
       end
 
+      # the parameters specified for this operation, plus any others scorpio considers to be parameters.
+      #
       # this method is not intended to be API-stable at the moment.
       #
-      # @return [#to_ary<#to_h>] the parameters specified for this operation, plus any others
-      #   scorpio considers to be parameters
+      # @api private
+      # @return [#to_ary<#to_h>]
       def inferred_parameters
         parameters = self.parameters ? self.parameters.to_a.dup : []
         path_template.variables.each do |var|
@@ -127,7 +139,8 @@ module Scorpio
         parameters
       end
 
-      # @return [Module] a module with accessor methods for unambiguously named parameters of this operation.
+      # a module with accessor methods for unambiguously named parameters of this operation.
+      # @return [Module]
       def request_accessor_module
         return @request_accessor_module if instance_variable_defined?(:@request_accessor_module)
         @request_accessor_module = begin
@@ -136,7 +149,7 @@ module Scorpio
             instance_method_modules = [Request, Request::Configurables]
             instance_method_names = instance_method_modules.map do |mod|
               (mod.instance_methods + mod.private_instance_methods).map(&:to_s)
-            end.inject(Set.new, &:|)
+            end.inject(Set.new, &:merge)
             params_by_name.each do |name, params|
               next if instance_method_names.include?(name)
               if params.size == 1
@@ -149,19 +162,22 @@ module Scorpio
         end
       end
 
-      # @param a, b are passed to Scorpio::Request#initialize
+      # instantiates a {Scorpio::Request} for this operation.
+      # parameters are all passed to {Scorpio::Request#initialize}.
       # @return [Scorpio::Request]
       def build_request(*a, &b)
         Scorpio::Request.new(self, *a, &b)
       end
 
-      # @param a, b are passed to Scorpio::Request#initialize
+      # runs a {Scorpio::Request} for this operation, returning a {Scorpio::Ur}.
+      # parameters are all passed to {Scorpio::Request#initialize}.
       # @return [Scorpio::Ur] response ur
       def run_ur(*a, &b)
         build_request(*a, &b).run_ur
       end
 
-      # @param a, b are passed to Scorpio::Request#initialize
+      # runs a {Scorpio::Request} for this operation - see {Scorpio::Request#run}.
+      # parameters are all passed to {Scorpio::Request#initialize}.
       # @return response body object
       def run(*a, &b)
         build_request(*a, &b).run
@@ -212,17 +228,19 @@ module Scorpio
             requestBody['content'] &&
             requestBody['content'][media_type] &&
             requestBody['content'][media_type]['schema']
-          schema_object ? JSI::Schema.from_object(schema_object) : nil
+          schema_object ? JSI::Schema.ensure_schema(schema_object) : nil
         end
 
-        # @return [Array<JSI::Schema>]
+        # @return [JSI::SchemaSet]
         def request_schemas
-          if requestBody && requestBody['content']
-            # oamt is for Scorpio::OpenAPI::V3::MediaType
-            oamts = requestBody['content'].values.select { |oamt| oamt.key?('schema') }
-            oamts.map { |oamt| JSI::Schema.from_object(oamt['schema']) }
-          else
-            []
+          JSI::SchemaSet.build do |schemas|
+            if requestBody && requestBody['content']
+              requestBody['content'].each_value do |oa_media_type|
+                if oa_media_type['schema']
+                  schemas << oa_media_type['schema']
+                end
+              end
+            end
           end
         end
 
@@ -232,7 +250,24 @@ module Scorpio
           oa_media_types = oa_response ? oa_response['content'] : nil # Scorpio::OpenAPI::V3::MediaTypes
           oa_media_type = oa_media_types ? oa_media_types[media_type] : nil # Scorpio::OpenAPI::V3::MediaType
           oa_schema = oa_media_type ? oa_media_type['schema'] : nil # Scorpio::OpenAPI::V3::Schema
-          oa_schema ? JSI::Schema.new(oa_schema) : nil
+          oa_schema ? JSI::Schema.ensure_schema(oa_schema) : nil
+        end
+
+        # @return [JSI::SchemaSet]
+        def response_schemas
+          JSI::SchemaSet.build do |schemas|
+            if responses
+              responses.each_value do |oa_response|
+                if oa_response['content']
+                  oa_response['content'].each_value do |oa_media_type|
+                    if oa_media_type['schema']
+                      schemas << oa_media_type['schema']
+                    end
+                  end
+                end
+              end
+            end
+          end
         end
       end
     end
@@ -264,7 +299,8 @@ module Scorpio
         end
         include Configurables
 
-        # @return [#to_hash] the body parameter
+        # the body parameter
+        # @return [#to_hash]
         # @raise [Scorpio::OpenAPI::SemanticError] if there's more than one body param
         def body_parameter
           body_parameters = (parameters || []).select { |parameter| parameter['in'] == 'body' }
@@ -278,19 +314,20 @@ module Scorpio
           end
         end
 
+        # request schema for the given media_type
         # @param media_type unused
-        # @return [JSI::Schema] request schema for the given media_type
+        # @return [JSI::Schema]
         def request_schema(media_type: nil)
           if body_parameter && body_parameter['schema']
-            JSI::Schema.new(body_parameter['schema'])
+            JSI::Schema.ensure_schema(body_parameter['schema'])
           else
             nil
           end
         end
 
-        # @return [Array<JSI::Schema>]
+        # @return [JSI::SchemaSet]
         def request_schemas
-          request_schema ? [request_schema] : []
+          request_schema ? JSI::SchemaSet[request_schema] : JSI::SchemaSet[]
         end
 
         # @param status [Integer, String] response status
@@ -299,7 +336,20 @@ module Scorpio
         def response_schema(status: , media_type: nil)
           oa_response = self.oa_response(status: status)
           oa_response_schema = oa_response ? oa_response['schema'] : nil # Scorpio::OpenAPI::V2::Schema
-          oa_response_schema ? JSI::Schema.new(oa_response_schema) : nil
+          oa_response_schema ? JSI::Schema.ensure_schema(oa_response_schema) : nil
+        end
+
+        # @return [JSI::SchemaSet]
+        def response_schemas
+          JSI::SchemaSet.build do |schemas|
+            if responses
+              responses.each_value do |oa_response|
+                if oa_response['schema']
+                  schemas << oa_response['schema']
+                end
+              end
+            end
+          end
         end
       end
     end

data/lib/scorpio/openapi/operations_scope.rb

@@ -1,13 +1,20 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     # OperationsScope acts as an Enumerable of the Operations for an openapi_document,
     # and offers subscripting by operationId.
     class OperationsScope
-      include JSI::Util::Memoize
-
       # @param openapi_document [Scorpio::OpenAPI::Document]
       def initialize(openapi_document)
         @openapi_document = openapi_document
+        @operations_by_id = Hash.new do |h, operationId|
+          op = detect { |operation| operation.operationId == operationId }
+          unless op
+            raise(::KeyError, "operationId not found: #{operationId.inspect}")
+          end
+          h[operationId] = op
+        end
       end
       attr_reader :openapi_document
 
@@ -23,17 +30,12 @@ module Scorpio
       end
       include Enumerable
 
-      # @param operationId
-      # @return [Scorpio::OpenAPI::Operation] the operation with the given operationId
+      # finds an operation with the given `operationId`
+      # @param operationId [String] the operationId of the operation to find
+      # @return [Scorpio::OpenAPI::Operation]
       # @raise [::KeyError] if the given operationId does not exist
       def [](operationId)
-        jsi_memoize(:[], operationId) do |operationId_|
-          detect { |operation| operation.operationId == operationId_ }.tap do |op|
-            unless op
-              raise(::KeyError, "operationId not found: #{operationId_.inspect}")
-            end
-          end
-        end
+        @operations_by_id[operationId]
       end
     end
   end

data/lib/scorpio/openapi/reference.rb

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     module Reference
       # overrides JSI::Base#[] to implicitly dereference this Reference, except when
       # the given token is present in this Reference's instance (this should usually
       # only apply to the token '$ref')
-      #
-      # see JSI::Base#initialize documentation at https://www.rubydoc.info/gems/jsi/JSI/Base
       def [](token, *a, &b)
         if respond_to?(:to_hash) && !key?(token)
           deref do |deref_jsi|
@@ -14,6 +14,31 @@ module Scorpio
         end
         return super
       end
+
+      # yields or returns the target of this reference
+      # @yield [JSI::Base] if a block is given
+      # @return [JSI::Base]
+      def deref
+        return unless respond_to?(:to_hash) && self['$ref'].respond_to?(:to_str)
+
+        ref_uri = Addressable::URI.parse(self['$ref'])
+        ref_uri_nofrag = ref_uri.merge(fragment: nil)
+
+        if !ref_uri_nofrag.empty? || ref_uri.fragment.nil?
+          raise(NotImplementedError,
+            "Scorpio currently only supports fragment URIs as OpenAPI references. cannot find reference by uri: #{self['$ref']}"
+          )
+        end
+
+        ptr = JSI::Ptr.from_fragment(ref_uri.fragment)
+        deref_jsi = ptr.evaluate(jsi_root_node)
+
+        # TODO type check deref_jsi
+
+        yield deref_jsi if block_given?
+
+        deref_jsi
+      end
     end
   end
 end

data/lib/scorpio/openapi/tag.rb

@@ -0,0 +1,15 @@
+module Scorpio
+  module OpenAPI
+    module Tag
+      # operations in the openapi document which have a tag with this tag's name
+      # @return [Enumerable<Scorpio::OpenAPI::Operation>]
+      def operations
+        unless jsi_root_node.is_a?(OpenAPI::Document)
+          raise("Tag#operations cannot be used on a Tag that is not inside an OpenAPI document")
+        end
+
+        jsi_root_node.operations.select { |op| op.tags.respond_to?(:to_ary) && op.tags.include?(name) }
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/v3/server.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     module V3
@@ -34,7 +36,7 @@ module Scorpio
             server_variables = given_server_variables
           end
           template = Addressable::Template.new(url)
-          template.expand(server_variables)
+          template.expand(server_variables).freeze
         end
       end
     end