scorpio 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 71c5dc59455a36015512d141156a3fde31869546
-  data.tar.gz: 0bce95f243957bd15832951224417510d7925f9b
+  metadata.gz: fef9d45f74d30432978fa58501add04b3fc60226
+  data.tar.gz: 2e8c5c985076afe3da550d1a8e1fe4c19a6f3b5d
 SHA512:
-  metadata.gz: 1c26985aac4d77d19bb97010ada163f50d5107710e20ffc076d8379bd6999d34e3de8b0c0782af5fe481b7faa847203424a4ad0ebc6c133844ee5cc1fcd712d1
-  data.tar.gz: 233edb5d4346b6cef88e0502aef2398850c657deb22055c6c142aaf6f5797608d79470e64e3ea140177220a7cf58001a725f15880cf8accff3dbfc3ae59d0d3a
+  metadata.gz: 8f1b1ff00e8c06761980421abb2c15b7bfc6584ab8db1e4fe4dc8159817d3a2ac827eca12e374c6851817b72d4b40e02b5577f164dc6e36a8514f4e5d69a86c3
+  data.tar.gz: c23470636bd6456a1d8bd23c469e4b6595c070b317fda0579a439b591077319471aa57daf12390bf81336a1a4068bb90c8f5ba09cc2f3ac3830c7f97ca6a1de2

data/CHANGELOG.md

@@ -1,3 +1,5 @@
+# v0.2.0
+
 # v0.1.0
 
 - Rewrite Model, use OpenAPI

data/README.md

@@ -1,10 +1,15 @@
 # Scorpio
 
-Scorpio is a library intended to make use of an OpenAPI document describing a service you are consuming or implementing, for various purposes.
+[![Build Status](https://travis-ci.org/notEthan/scorpio.svg?branch=master)](https://travis-ci.org/notEthan/scorpio)
+[![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 specification, 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.
+
+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.
 
 ## Background
 
-To start with, you need an OpenAPI v2 (formerly known as Swagger) document describing a service. v3 support is planned. 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 v2 (formerly known as Swagger) document describing a service you will be consuming. v3 support is planned. 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
@@ -13,48 +18,126 @@ To start with, you need an OpenAPI v2 (formerly known as Swagger) document descr
 
 OpenAPI relies on the definition of schemas using the JSON schema specification, which can be learned about at http://json-schema.org/
 
-## Scorpio::Model
+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::Model aims to represent RESTful resources in ruby classes with as little code as possible, given a service with a properly constructed API specification.
+## Pet Store
 
-A model representing a resource needs to be configured, minimally, with:
+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 )
 
-- the OpenAPI specification for the REST API
-- the base URL where the service is deployed, relative to which are the paths of the API description
-- the schema(s) the model represents
+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.
 
-If the resource has HTTP methods associated with it (most, but not all resources will):
+```ruby
+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.
+  #
+  # 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('http://petstore.swagger.io/v2/swagger.json').body)
+  end
+
+  # 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.
+    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.
+    #
+    # 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.
+    self.represented_schemas = [openapi_document.definitions['Pet']]
+  end
+end
+```
 
-- the name of the resource corresponding to the model
+That should be all you need to start calling operations:
 
-When these are set, Scorpio::Model looks through the API description and dynamically sets up methods for the model:
+```ruby
+# call the operation findPetsByStatus: http://petstore.swagger.io/#/pet/findPetsByStatus
+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.
+
+pet1.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"]
+
+# let's name the pet after ourself
+pet1.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
+
+# check that it was saved
+PetStore::Pet.getPetById(petId: pet1['id']).name
+# => "ethan" (unless for some reason your name is not Ethan)
+
+# here is how errors are handled:
+PetStore::Pet.getPetById(petId: 0)
+# raises: Scorpio::HTTPErrors::NotFound404Error
+#   Error calling operation getPetById on PetStore::Pet:
+#   {"code":1,"type":"error","message":"Pet not found"}
+```
 
-- accessors for properties of the model defined as properties of schemas representing the resource in the specification
-- API method calls on the model class and, where appropriate, on the model instance
+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.
+
+### Another Example: Blog
 
-### Example: Blog
+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.
 
-Scorpio's tests are a good place to read example code of an API that a client interacts with using Scorpio::Model.
+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`.
 
-The Blog service is defined in test/blog.rb. It uses ActiveRecord models and Sinatra to make a simple RESTful service.
+## Scorpio::ResourceBase
 
-Its API is described in `test/blog.openapi.yml`, defining the Article resource, several methods (some of which are instance methods), and schemas.
+Scorpio::ResourceBase is the main class used in abstracting on OpenAPI document. Scorpio::ResourceBase aims to represent RESTful resources in ruby classes with as little code as possible, given a service with a properly constructed OpenAPI specification.
 
-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.
+A class which subclasses Scorpio::ResourceBase directly (such as PetStore::Resource above) should generally represent the whole API - you set the openapi_document and other configuration on this class. As such, it is generally not instantiated. Its subclasses, representing resources with a tag or with schema definitions in the OpenAPI document, are what you mostly instantiate and interact with.
 
-The Article model inherits from BlogModel and is set with its resource name and the keys of its schema in the API description.
+A model representing a resource needs to be configured, minimally, with:
+
+- the OpenAPI specification for the REST API
+- the schemas that represent instances of the model, if any
 
-Based on those, Article gets the methods of the API description which are tested in `test/scorpio_test.rb`.
+If the resource has HTTP operations associated with it (most, but not all resources will):
 
-[This section will be fleshed out with more description and less just telling you, dear reader, to read the test code, as development progresses.]
+- a tag name identifying its tagged operations
+
+When these are set, Scorpio::ResourceBase looks through the API description and dynamically sets up methods for the model:
+
+- accessors for properties of the model defined as properties of schemas representing the resource in the specification
+- API method calls on the model class and, where appropriate, on the model instance
 
-### Scorpio Model pickle adapter
+### Scorpio ResourceBase pickle adapter
 
 Scorpio provides a pickle adapter to use models with [Pickle](https://rubygems.org/gems/pickle). `require 'scorpio/pickle_adapter'`, ensure that the pickle ORM adapter is enabled, and you should be able to create models as normal with pickle.
 
 ### Google API discovery service
 
-An initial implementation of Scorpio::Model was based on the format defined for Google's API discovery service.
+An initial implementation of Scorpio::ResourceBase was based on the format defined for Google's API discovery service.
 
 For background on the Google discovery service and the API description format it defines, see:
 
@@ -64,10 +147,10 @@ For background on the Google discovery service and the API description format it
 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::Model
+class MyModel < Scorpio::ResourceBase
   rest_description_doc = YAML.load_file('path/to/doc.yml')
   rest_description = Scorpio::Google::RestDescription.new(rest_description_doc)
-  set_openapi_document(rest_description.to_openapi_document)
+  self.openapi_document = rest_description.to_openapi_document
 
   # ... the remainder of your setup and model code here
 end

data/Rakefile

@@ -1,4 +1,3 @@
-require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
@@ -7,4 +6,5 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+require 'wwtd/tasks'
+task 'default' => 'wwtd'

data/documents/openapis.org/v3/schema.json

@@ -0,0 +1,1239 @@
+{
+  "title": "A JSON Schema for OpenAPI 3.0.",
+  "id": "http://openapis.org/v3/schema.json#",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "description": "This is the root document object of the OpenAPI document.",
+  "required": [
+    "openapi",
+    "info",
+    "paths"
+  ],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {
+      "$ref": "#/definitions/specificationExtension"
+    }
+  },
+  "properties": {
+    "openapi": {
+      "type": "string"
+    },
+    "info": {
+      "$ref": "#/definitions/info"
+    },
+    "servers": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/server"
+      },
+      "uniqueItems": true
+    },
+    "paths": {
+      "$ref": "#/definitions/paths"
+    },
+    "components": {
+      "$ref": "#/definitions/components"
+    },
+    "security": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/securityRequirement"
+      },
+      "uniqueItems": true
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/tag"
+      },
+      "uniqueItems": true
+    },
+    "externalDocs": {
+      "$ref": "#/definitions/externalDocs"
+    }
+  },
+  "definitions": {
+    "info": {
+      "type": "object",
+      "description": "The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.",
+      "required": [
+        "title",
+        "version"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "title": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "termsOfService": {
+          "type": "string"
+        },
+        "contact": {
+          "$ref": "#/definitions/contact"
+        },
+        "license": {
+          "$ref": "#/definitions/license"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "contact": {
+      "type": "object",
+      "description": "Contact information for the exposed API.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        }
+      }
+    },
+    "license": {
+      "type": "object",
+      "description": "License information for the exposed API.",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      }
+    },
+    "server": {
+      "type": "object",
+      "description": "An object representing a Server.",
+      "required": [
+        "url"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "url": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "variables": {
+          "$ref": "#/definitions/serverVariables"
+        }
+      }
+    },
+    "serverVariable": {
+      "type": "object",
+      "description": "An object representing a Server Variable for server URL template substitution.",
+      "required": [
+        "default"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "enum": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "default": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "components": {
+      "type": "object",
+      "description": "Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "schemas": {
+          "$ref": "#/definitions/schemasOrReferences"
+        },
+        "responses": {
+          "$ref": "#/definitions/responsesOrReferences"
+        },
+        "parameters": {
+          "$ref": "#/definitions/parametersOrReferences"
+        },
+        "examples": {
+          "$ref": "#/definitions/examplesOrReferences"
+        },
+        "requestBodies": {
+          "$ref": "#/definitions/requestBodiesOrReferences"
+        },
+        "headers": {
+          "$ref": "#/definitions/headersOrReferences"
+        },
+        "securitySchemes": {
+          "$ref": "#/definitions/securitySchemesOrReferences"
+        },
+        "links": {
+          "$ref": "#/definitions/linksOrReferences"
+        },
+        "callbacks": {
+          "$ref": "#/definitions/callbacksOrReferences"
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "description": "Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the `Server Object` in order to construct the full URL.  The Paths MAY be empty, due to ACL constraints.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^/": {
+          "$ref": "#/definitions/pathItem"
+        },
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      }
+    },
+    "pathItem": {
+      "type": "object",
+      "description": "Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "$ref": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "get": {
+          "$ref": "#/definitions/operation"
+        },
+        "put": {
+          "$ref": "#/definitions/operation"
+        },
+        "post": {
+          "$ref": "#/definitions/operation"
+        },
+        "delete": {
+          "$ref": "#/definitions/operation"
+        },
+        "options": {
+          "$ref": "#/definitions/operation"
+        },
+        "head": {
+          "$ref": "#/definitions/operation"
+        },
+        "patch": {
+          "$ref": "#/definitions/operation"
+        },
+        "trace": {
+          "$ref": "#/definitions/operation"
+        },
+        "servers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/server"
+          },
+          "uniqueItems": true
+        },
+        "parameters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/parameterOrReference"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "operation": {
+      "type": "object",
+      "description": "Describes a single API operation on a path.",
+      "required": [
+        "responses"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "summary": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "externalDocs": {
+          "$ref": "#/definitions/externalDocs"
+        },
+        "operationId": {
+          "type": "string"
+        },
+        "parameters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/parameterOrReference"
+          },
+          "uniqueItems": true
+        },
+        "requestBody": {
+          "$ref": "#/definitions/requestBodyOrReference"
+        },
+        "responses": {
+          "$ref": "#/definitions/responses"
+        },
+        "callbacks": {
+          "$ref": "#/definitions/callbacksOrReferences"
+        },
+        "deprecated": {
+          "type": "boolean"
+        },
+        "security": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/securityRequirement"
+          },
+          "uniqueItems": true
+        },
+        "servers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/server"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "externalDocs": {
+      "type": "object",
+      "description": "Allows referencing an external resource for extended documentation.",
+      "required": [
+        "url"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      }
+    },
+    "parameter": {
+      "type": "object",
+      "description": "Describes a single operation parameter.  A unique parameter is defined by a combination of a name and location.",
+      "required": [
+        "name",
+        "in"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "in": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "deprecated": {
+          "type": "boolean"
+        },
+        "allowEmptyValue": {
+          "type": "boolean"
+        },
+        "style": {
+          "type": "string"
+        },
+        "explode": {
+          "type": "boolean"
+        },
+        "allowReserved": {
+          "type": "boolean"
+        },
+        "schema": {
+          "$ref": "#/definitions/schemaOrReference"
+        },
+        "example": {
+          "$ref": "#/definitions/any"
+        },
+        "examples": {
+          "$ref": "#/definitions/examplesOrReferences"
+        },
+        "content": {
+          "$ref": "#/definitions/mediaTypes"
+        }
+      }
+    },
+    "requestBody": {
+      "type": "object",
+      "description": "Describes a single request body.",
+      "required": [
+        "content"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "content": {
+          "$ref": "#/definitions/mediaTypes"
+        },
+        "required": {
+          "type": "boolean"
+        }
+      }
+    },
+    "mediaType": {
+      "type": "object",
+      "description": "Each Media Type Object provides schema and examples for the media type identified by its key.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "schema": {
+          "$ref": "#/definitions/schemaOrReference"
+        },
+        "example": {
+          "$ref": "#/definitions/any"
+        },
+        "examples": {
+          "$ref": "#/definitions/examplesOrReferences"
+        },
+        "encoding": {
+          "$ref": "#/definitions/encodings"
+        }
+      }
+    },
+    "encoding": {
+      "type": "object",
+      "description": "A single encoding definition applied to a single schema property.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "contentType": {
+          "type": "string"
+        },
+        "headers": {
+          "$ref": "#/definitions/headersOrReferences"
+        },
+        "style": {
+          "type": "string"
+        },
+        "explode": {
+          "type": "boolean"
+        },
+        "allowReserved": {
+          "type": "boolean"
+        }
+      }
+    },
+    "responses": {
+      "type": "object",
+      "description": "A container for the expected responses of an operation. The container maps a HTTP response code to the expected response.  The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.  The `default` MAY be used as a default response object for all HTTP codes  that are not covered individually by the specification.  The `Responses Object` MUST contain at least one response code, and it  SHOULD be the response for a successful operation call.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^([0-9X]{3})$": {
+          "$ref": "#/definitions/responseOrReference"
+        },
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "default": {
+          "$ref": "#/definitions/responseOrReference"
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "description": "Describes a single response from an API Operation, including design-time, static  `links` to operations based on the response.",
+      "required": [
+        "description"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "headers": {
+          "$ref": "#/definitions/headersOrReferences"
+        },
+        "content": {
+          "$ref": "#/definitions/mediaTypes"
+        },
+        "links": {
+          "$ref": "#/definitions/linksOrReferences"
+        }
+      }
+    },
+    "callback": {
+      "type": "object",
+      "description": "A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^": {
+          "$ref": "#/definitions/pathItem"
+        },
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      }
+    },
+    "example": {
+      "type": "object",
+      "description": "",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "summary": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "value": {
+          "$ref": "#/definitions/any"
+        },
+        "externalValue": {
+          "type": "string"
+        }
+      }
+    },
+    "link": {
+      "type": "object",
+      "description": "The `Link object` represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.  Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response.  For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "operationRef": {
+          "type": "string"
+        },
+        "operationId": {
+          "type": "string"
+        },
+        "parameters": {
+          "$ref": "#/definitions/anysOrExpressions"
+        },
+        "requestBody": {
+          "$ref": "#/definitions/anyOrExpression"
+        },
+        "description": {
+          "type": "string"
+        },
+        "server": {
+          "$ref": "#/definitions/server"
+        }
+      }
+    },
+    "header": {
+      "type": "object",
+      "description": "The Header Object follows the structure of the Parameter Object with the following changes:  1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, `style`).",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "deprecated": {
+          "type": "boolean"
+        },
+        "allowEmptyValue": {
+          "type": "boolean"
+        },
+        "style": {
+          "type": "string"
+        },
+        "explode": {
+          "type": "boolean"
+        },
+        "allowReserved": {
+          "type": "boolean"
+        },
+        "schema": {
+          "$ref": "#/definitions/schemaOrReference"
+        },
+        "example": {
+          "$ref": "#/definitions/any"
+        },
+        "examples": {
+          "$ref": "#/definitions/examplesOrReferences"
+        },
+        "content": {
+          "$ref": "#/definitions/mediaTypes"
+        }
+      }
+    },
+    "tag": {
+      "type": "object",
+      "description": "Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "externalDocs": {
+          "$ref": "#/definitions/externalDocs"
+        }
+      }
+    },
+    "examples": {
+      "type": "object",
+      "description": "",
+      "additionalProperties": false
+    },
+    "reference": {
+      "type": "object",
+      "description": "A simple object to allow referencing other components in the specification, internally and externally.  The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.   For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.",
+      "required": [
+        "$ref"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": {
+          "type": "string"
+        }
+      }
+    },
+    "schema": {
+      "type": "object",
+      "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.  For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "nullable": {
+          "type": "boolean"
+        },
+        "discriminator": {
+          "$ref": "#/definitions/discriminator"
+        },
+        "readOnly": {
+          "type": "boolean"
+        },
+        "writeOnly": {
+          "type": "boolean"
+        },
+        "xml": {
+          "$ref": "#/definitions/xml"
+        },
+        "externalDocs": {
+          "$ref": "#/definitions/externalDocs"
+        },
+        "example": {
+          "$ref": "#/definitions/any"
+        },
+        "deprecated": {
+          "type": "boolean"
+        },
+        "title": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/title"
+        },
+        "multipleOf": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf"
+        },
+        "maximum": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/maximum"
+        },
+        "exclusiveMaximum": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum"
+        },
+        "minimum": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/minimum"
+        },
+        "exclusiveMinimum": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum"
+        },
+        "maxLength": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/maxLength"
+        },
+        "minLength": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/minLength"
+        },
+        "pattern": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/pattern"
+        },
+        "maxItems": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/maxItems"
+        },
+        "minItems": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/minItems"
+        },
+        "uniqueItems": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems"
+        },
+        "maxProperties": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/maxProperties"
+        },
+        "minProperties": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/minProperties"
+        },
+        "required": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/required"
+        },
+        "enum": {
+          "$ref": "http://json-schema.org/draft-04/schema#/properties/enum"
+        },
+        "type": {
+          "type": "string"
+        },
+        "allOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/schemaOrReference"
+          },
+          "minItems": 1
+        },
+        "oneOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/schemaOrReference"
+          },
+          "minItems": 1
+        },
+        "anyOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/schemaOrReference"
+          },
+          "minItems": 1
+        },
+        "not": {
+          "$ref": "#/definitions/schema"
+        },
+        "items": {
+          "$ref": "#/definitions/schemaOrReference"
+        },
+        "properties": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/schemaOrReference"
+          }
+        },
+        "additionalProperties": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/schemaOrReference"
+            },
+            {
+              "type": "boolean"
+            }
+          ]
+        },
+        "default": {
+          "$ref": "#/definitions/defaultType"
+        },
+        "description": {
+          "type": "string"
+        },
+        "format": {
+          "type": "string"
+        }
+      }
+    },
+    "discriminator": {
+      "type": "object",
+      "description": "When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.  When using the discriminator, _inline_ schemas will not be considered.",
+      "required": [
+        "propertyName"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "propertyName": {
+          "type": "string"
+        },
+        "mapping": {
+          "$ref": "#/definitions/strings"
+        }
+      }
+    },
+    "xml": {
+      "type": "object",
+      "description": "A metadata object that allows for more fine-tuned XML model definitions.  When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "namespace": {
+          "type": "string"
+        },
+        "prefix": {
+          "type": "string"
+        },
+        "attribute": {
+          "type": "boolean"
+        },
+        "wrapped": {
+          "type": "boolean"
+        }
+      }
+    },
+    "securityScheme": {
+      "type": "object",
+      "description": "Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, and OpenID Connect Discovery.",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "in": {
+          "type": "string"
+        },
+        "scheme": {
+          "type": "string"
+        },
+        "bearerFormat": {
+          "type": "string"
+        },
+        "flows": {
+          "$ref": "#/definitions/oauthFlows"
+        },
+        "openIdConnectUrl": {
+          "type": "string"
+        }
+      }
+    },
+    "oauthFlows": {
+      "type": "object",
+      "description": "Allows configuration of the supported OAuth Flows.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "implicit": {
+          "$ref": "#/definitions/oauthFlow"
+        },
+        "password": {
+          "$ref": "#/definitions/oauthFlow"
+        },
+        "clientCredentials": {
+          "$ref": "#/definitions/oauthFlow"
+        },
+        "authorizationCode": {
+          "$ref": "#/definitions/oauthFlow"
+        }
+      }
+    },
+    "oauthFlow": {
+      "type": "object",
+      "description": "Configuration details for a supported OAuth Flow",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "#/definitions/specificationExtension"
+        }
+      },
+      "properties": {
+        "authorizationUrl": {
+          "type": "string"
+        },
+        "tokenUrl": {
+          "type": "string"
+        },
+        "refreshUrl": {
+          "type": "string"
+        },
+        "scopes": {
+          "$ref": "#/definitions/strings"
+        }
+      }
+    },
+    "securityRequirement": {
+      "type": "object",
+      "description": "Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the Security Schemes under the Components Object.  Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.  When a list of Security Requirement Objects is defined on the Open API object or Operation Object, only one of Security Requirement Objects in the list needs to be satisfied to authorize the request.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-zA-Z0-9\\.\\-_]+$": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "anyOrExpression": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/any"
+        },
+        {
+          "$ref": "#/definitions/expression"
+        }
+      ]
+    },
+    "callbackOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/callback"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "exampleOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/example"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "headerOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/header"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "linkOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/link"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "parameterOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/parameter"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "requestBodyOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/requestBody"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "responseOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/response"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "schemaOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/schema"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "securitySchemeOrReference": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/securityScheme"
+        },
+        {
+          "$ref": "#/definitions/reference"
+        }
+      ]
+    },
+    "anysOrExpressions": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/anyOrExpression"
+      }
+    },
+    "callbacksOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/callbackOrReference"
+      }
+    },
+    "encodings": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/encoding"
+      }
+    },
+    "examplesOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/exampleOrReference"
+      }
+    },
+    "headersOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/headerOrReference"
+      }
+    },
+    "linksOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/linkOrReference"
+      }
+    },
+    "mediaTypes": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/mediaType"
+      }
+    },
+    "parametersOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/parameterOrReference"
+      }
+    },
+    "requestBodiesOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/requestBodyOrReference"
+      }
+    },
+    "responsesOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/responseOrReference"
+      }
+    },
+    "schemasOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/schemaOrReference"
+      }
+    },
+    "securitySchemesOrReferences": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/securitySchemeOrReference"
+      }
+    },
+    "serverVariables": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/serverVariable"
+      }
+    },
+    "strings": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "object": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "any": {
+      "additionalProperties": true
+    },
+    "expression": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "specificationExtension": {
+      "description": "Any property starting with x- is valid.",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string"
+        },
+        {
+          "type": "object"
+        },
+        {
+          "type": "array"
+        }
+      ]
+    },
+    "defaultType": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "array"
+        },
+        {
+          "type": "object"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string"
+        }
+      ]
+    }
+  }
+}