scorpio 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 603bcc3914e849b35e8c4519682588fc7f56dda8d52c188fde80eef20bf7b34f
-  data.tar.gz: aecb035dd48a48c8f97e7ca60ffb560abde598385db4cbaf4d0444226708a7ef
+  metadata.gz: 510fd6b2b4dc5e78a4d11c08dcb7fc53901b308a4eef0b53d3d7317aabdd265f
+  data.tar.gz: d2c92b80c26f24f5f98540c456b2177d74bc13e5a2e5f461a531525631afff96
 SHA512:
-  metadata.gz: e462291e8caca9542c8de14c81402be9bb004571c93d2af7ce92d842ee22861df92a10e9be941149950d017d7751d41e70d6ada8bb17fb2822c0ba85a0a8cbd9
-  data.tar.gz: 6cc6ebc90878d29cc2861c7c48e2231cd5554b7ed569efcbe529295275969d772f9bb1c328039d539ef4e579489f37269ae2003bd6a2d15da90645548cedafe9
+  metadata.gz: 52561bf683728001d750987ae8eb8df5356b75db3c0e1b734182a3af69227c4db6e4699d94b1a8f820802b5c5d804c9d73eebf49ea05991c309ef6b20d9ce8ff
+  data.tar.gz: 8144a386a93d397193ea952965d3de6bf398739a4b2c20a2e8dfcbd716f9721a3eae9949f5714695ce83e338353c8152954e1bee130af198973a41f7edb9e854

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# v0.4.2
+- improve documentation
+- misc bugfixes
+
 # v0.4.1
 - Request#param_for
 - Operation#human_id

data/README.md

@@ -9,7 +9,7 @@ Note: The canonical location of this README is on [RubyDoc](http://rubydoc.info/
 
 ## 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 specifying your service is outside the scope of Scorpio. Here are several resources on OpenAPI:
+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 specifying your service is outside the scope of Scorpio. Here are several resources on OpenAPI:
 
 - [OpenAPI Specification at Wikipedia](https://en.wikipedia.org/wiki/OpenAPI_Specification)
 - [OpenAPI Initiative](https://www.openapis.org/) is the official web site for OpenAPI
@@ -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/ and its OpenAPI 2 specification is at http://petstore.swagger.io/v2/swagger.json (yaml version: http://petstore.swagger.io/v2/swagger.yaml )
+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/.
 
 Using the specification, we can start interacting with the pet store with very little code. Here is that code, with explanations of each part in the comments.
 
@@ -71,31 +71,29 @@ That should be all you need to start calling operations:
 sold_pets = PetStore::Pet.findPetsByStatus(status: 'sold')
 # sold_pets is an array-like collection of PetStore::Pet instances
 
-# compare to getPetById: http://petstore.swagger.io/#/pet/getPetById
-pet1 = sold_pets.last
-pet2 = PetStore::Pet.getPetById(petId: pet1['id'])
-# pet2 is the same pet as pet1, retrieved using the getPetById operation
-
-pet1 == pet2
-# should return true. they are the same pet.
+pet = sold_pets.sample
 
-pet1.tags.map(&:name)
+pet.tags.map(&:name)
 # note that you have accessors on PetStore::Pet 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 == PetStore::Pet.getPetById(petId: pet['id'])
+# pet is the same, retrieved using the getPetById operation
+
 # let's name the pet after ourself
-pet1.name = ENV['USER']
+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
-pet1.updatePet
+pet.updatePet
 
 # check that it was saved
-PetStore::Pet.getPetById(petId: pet1['id']).name
+PetStore::Pet.getPetById(petId: pet['id']).name
 # => "ethan" (unless for some reason your name is not Ethan)
 
 # here is how errors are handled:
@@ -158,29 +156,28 @@ let's pick a state and find a pet. we'll go through the rest of the example in t
 sold_pets = pet_store_doc.operations['findPetsByStatus'].run(status: 'sold')
 # sold_pets is an array-like collection of JSI instances
 
-# compare to getPetById: http://petstore.swagger.io/#/pet/getPetById
-pet1 = sold_pets.detect { |pet| pet.tags.any? }
-pet2 = pet_store_doc.operations['getPetById'].run(petId: pet1['id'])
-# without ResourceBase, pet1 and pet2 are not considered to be the same though [TODO may change in jsi]
-
-pet1 == pet2
-# false
+pet = sold_pets.detect { |pet| pet.tags.any? }
 
-pet1.tags.map(&:name)
+pet.tags.map(&:name)
 # note that you have accessors on PetStore::Pet 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'])
+# => false
+# without ResourceBase, pet is not considered to be the same compared with getPetById [TODO may change in jsi]
+
 # let's name the pet after ourself
-pet1.name = ENV['USER']
+pet.name = ENV['USER']
 
 # store the result in the pet store.
 # updatePet: http://petstore.swagger.io/#/pet/updatePet
-pet_store_doc.operations['updatePet'].run(body_object: pet1)
+pet_store_doc.operations['updatePet'].run(body_object: pet)
 
 # check that it was saved
-pet_store_doc.operations['getPetById'].run(petId: pet1['id']).name
+pet_store_doc.operations['getPetById'].run(petId: pet['id']).name
 # => "ethan" (unless for some reason your name is not Ethan)
 
 # here is how errors are handled:

data/lib/scorpio/openapi/document.rb

@@ -84,7 +84,7 @@ module Scorpio
     end
 
     module V3
-      raise(Bug) unless const_defined?(:Document)
+      raise(Bug, 'const_defined? Scorpio::OpenAPI::V3::Document') unless const_defined?(:Document)
 
       # A document that defines or describes an API conforming to the OpenAPI Specification v3.
       #
@@ -127,7 +127,7 @@ module Scorpio
     end
 
     module V2
-      raise(Bug) unless const_defined?(:Document)
+      raise(Bug, 'const_defined? Scorpio::OpenAPI::V2::Document') unless const_defined?(:Document)
 
       # A document that defines or describes an API conforming to the OpenAPI Specification v2 (aka Swagger).
       #

data/lib/scorpio/openapi/operation.rb

@@ -87,6 +87,8 @@ 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
       def http_method
         return @http_method if instance_variable_defined?(:@http_method)
         @http_method = begin
@@ -155,21 +157,27 @@ module Scorpio
         end
       end
 
+      # @param a, b are 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
+      # @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
+      # @return response body object
       def run(*a, &b)
         build_request(*a, &b).run
       end
     end
 
     module V3
-      raise(Bug) unless const_defined?(:Operation)
+      raise(Bug, 'const_defined? Scorpio::OpenAPI::V3::Operation') unless const_defined?(:Operation)
 
       # Describes a single API operation on a path.
       #
@@ -205,6 +213,7 @@ module Scorpio
         end
         include Configurables
 
+        # @return [JSI::Schema]
         def request_schema(media_type: self.request_media_type)
           # TODO typechecking on requestBody & children
           schema_object = requestBody &&
@@ -214,6 +223,7 @@ module Scorpio
           schema_object ? JSI::Schema.from_object(schema_object) : nil
         end
 
+        # @return [Array<JSI::Schema>]
         def request_schemas
           if requestBody && requestBody['content']
             # oamt is for Scorpio::OpenAPI::V3::MediaType
@@ -224,7 +234,7 @@ module Scorpio
           end
         end
 
-        # @return JSI::Schema
+        # @return [JSI::Schema]
         def response_schema(status: , media_type: )
           oa_response = self.oa_response(status: status)
           oa_media_types = oa_response ? oa_response['content'] : nil # Scorpio::OpenAPI::V3::MediaTypes
@@ -235,7 +245,7 @@ module Scorpio
       end
     end
     module V2
-      raise(Bug) unless const_defined?(:Operation)
+      raise(Bug, 'const_defined? Scorpio::OpenAPI::V2::Operation') unless const_defined?(:Operation)
       class Operation
         module Configurables
           attr_writer :scheme
@@ -275,6 +285,8 @@ module Scorpio
           end
         end
 
+        # @param media_type unused
+        # @return [JSI::Schema] request schema for the given media_type
         def request_schema(media_type: nil)
           if body_parameter && body_parameter['schema']
             JSI::Schema.new(body_parameter['schema'])
@@ -283,11 +295,14 @@ module Scorpio
           end
         end
 
+        # @return [Array<JSI::Schema>]
         def request_schemas
           request_schema ? [request_schema] : []
         end
 
-        # @return JSI::Schema
+        # @param status [Integer, String] response status
+        # @param media_type unused
+        # @return [JSI::Schema]
         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

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

@@ -1,7 +1,7 @@
 module Scorpio
   module OpenAPI
     module V3
-      raise(Bug) unless const_defined?(:Server)
+      raise(Bug, 'const_defined? Scorpio::OpenAPI::V3::Server') unless const_defined?(:Server)
 
       # An object representing a Server.
       #

data/lib/scorpio/request.rb

@@ -240,7 +240,7 @@ module Scorpio
     # @param name [String, Symbol] the 'name' property of one applicable parameter
     # @param value [Object] the applicable parameter will be applied to the request with the given value.
     # @return [Object] echoes the value param
-    # @raise [Scorpio::AmbiguousParameter] if more than one paramater has the given name
+    # @raise [Scorpio::AmbiguousParameter] if more than one parameter has the given name
     def set_param(name, value)
       param = param_for!(name)
       set_param_from(param['in'], param['name'], value)
@@ -249,7 +249,7 @@ module Scorpio
 
     # @param name [String, Symbol] the 'name' property of one applicable parameter
     # @return [Object] the value of the named parameter on this request
-    # @raise [Scorpio::AmbiguousParameter] if more than one paramater has the given name
+    # @raise [Scorpio::AmbiguousParameter] if more than one parameter has the given name
     def get_param(name)
       param = param_for!(name)
       get_param_from(param['in'], param['name'])

data/lib/scorpio/resource_base.rb

@@ -427,10 +427,13 @@ module Scorpio
         end
 
         if object.respond_to?(:to_hash)
-          out = JSI::Typelike.modified_copy(object) do
-            object.map do |key, value|
+          out = JSI::Typelike.modified_copy(object) do |_object|
+            mod = object.map do |key, value|
               {key => response_object_to_instances(value, initialize_options)}
             end.inject({}, &:update)
+            mod = mod.instance if mod.is_a?(JSI::Base)
+            mod = mod.content if mod.is_a?(JSI::JSON::Node)
+            mod
           end
           if model
             model.new(out, initialize_options)

data/lib/scorpio/version.rb

@@ -1,3 +1,3 @@
 module Scorpio
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scorpio
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Ethan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-05-26 00:00:00.000000000 Z
+date: 2019-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jsi