scorpio 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb674493cc2557d4679ac5eb54e8734251cddd9005410ad6f5a2c5f1db662380
-  data.tar.gz: 1bd8308607be18331a71be7cd74627b0138aad7b6d575c887ec4f9d05d263e5c
+  metadata.gz: f65533b3372858d91ff71a0ec3847179a8f50a1d825e5f77e94632a249692ecc
+  data.tar.gz: 7dab437fe9bbe813f2b8a24417d0232fdf39dc861c2723b7f5df74764cf92797
 SHA512:
-  metadata.gz: e81ef200e242f7cc3a616e628bf3eaa68029effbeb0c25c7f76d2e0760e7493b2d57a3b04be492c2f674b51453c2d92a015099dbc6ed9d82a3bc478e27bd6630
-  data.tar.gz: 17f680366d8e6c8ef67d8755a643fdaea7ad9b4fbb4e6d86b3d603df92628fc450353b26f11a86d27b2317d0609bd36f743be22b56c7547630c2b815928f27fb
+  metadata.gz: 13c15b82acc7509c807336037993fa6e97bd7308a37e552974ae259b2665230a78a83235d455df485b51c318c76e8f64ed2e4397bcdc24b4ede52b32e58945f2
+  data.tar.gz: c25e928331ff2e0a00904c0e7db4fef1fd5d3ed77331acd6e3b2e59905301ef1d958ec3346eca92f98298c8b2a1ef1e3b537eaf874d87e128c933108d31fcea5

data/.yardopts

@@ -0,0 +1 @@
+--main README.md --markup=markdown {lib}/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.4.0
+- Scorpio::OpenAPI v3 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
+- many refactorings, improvements, and fixes
+
 # v0.3.1
 - miscellaneous minor fixes and improvements
 

data/README.md

@@ -20,9 +20,9 @@ OpenAPI relies on the definition of schemas using the JSON schema specification,
 
 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.
 
-[^1] Certain features may be missing, but Scorpio tries to make workarounds easy. Issues and pull requests regarding missing functionality are welcome.
+[^1]: Certain features may be missing, but Scorpio tries to make workarounds easy. Issues and pull requests regarding missing functionality are welcome.
 
-## Pet Store
+## 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 )
 
@@ -107,6 +107,89 @@ 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)
+
+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.
+
+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))
+# => #{<Scorpio::OpenAPI::V2::Document fragment="#"> "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.
+
+```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">
+#      "summary" => "Returns pet inventories by status",
+#      "operationId" => "getInventory",
+#      ...
+#    }
+```
+
+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`:
+
+```ruby
+inventory_op = pet_store_doc.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).
+
+```ruby
+inventory = inventory_op.run
+# => #{<JSI::SchemaClasses["dde3#/paths/~1store~1inventory/get/responses/200/schema"] fragment="#">
+#      "unavailable" => 4,
+#      "unloved - needs a home" => 1,
+#      "available" => 2350,
+#      "sold" => 5790,
+#      "dog" => 1,
+#    }
+```
+
+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
+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
+
+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.
+# updatePet: http://petstore.swagger.io/#/pet/updatePet
+pet_store_doc.operations['updatePet'].run(body_object: pet1)
+
+# check that it was saved
+pet_store_doc.operations['getPetById'].run(petId: pet1['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)
+# raises: Scorpio::HTTPErrors::NotFound404Error
+#   Error calling operation getPetById:
+#   {"code":1,"type":"error","message":"Pet not found"}
+```
+
 ### Another 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.
@@ -133,6 +216,16 @@ When these are set, Scorpio::ResourceBase looks through the API description and
 - 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::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:
+
+```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_ur = inventory_op.run_ur
+# => #{<Scorpio::Ur fragment="#"> ...}
+```
+
 ### 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.

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

@@ -0,0 +1,1495 @@
+type: object
+required:
+  - openapi
+  - info
+  - paths
+properties:
+  openapi:
+    type: string
+    pattern: ^3\.0\.\d(-.+)?$
+  info:
+    $ref: '#/definitions/Info'
+  externalDocs:
+    $ref: '#/definitions/ExternalDocumentation'
+  servers:
+    type: array
+    items:
+      $ref: '#/definitions/Server'
+  security:
+    type: array
+    items:
+      $ref: '#/definitions/SecurityRequirement'
+  tags:
+    type: array
+    items:
+      $ref: '#/definitions/Tag'
+    uniqueItems: true
+  paths:
+    $ref: '#/definitions/Paths'
+  components:
+    $ref: '#/definitions/Components'
+patternProperties:
+  '^x-': {}
+additionalProperties: false
+definitions:
+  Reference:
+    type: object
+    required:
+      - $ref
+    patternProperties:
+      '^\$ref$':
+        type: string
+        format: uri-reference
+  Info:
+    type: object
+    required:
+      - title
+      - version
+    properties:
+      title:
+        type: string
+      description:
+        type: string
+      termsOfService:
+        type: string
+        format: uri-reference
+      contact:
+        $ref: '#/definitions/Contact'
+      license:
+        $ref: '#/definitions/License'
+      version:
+        type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+
+  Contact:
+    type: object
+    properties:
+      name:
+        type: string
+      url:
+        type: string
+        format: uri-reference
+      email:
+        type: string
+        format: email
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false    
+
+  License:
+    type: object
+    required:
+      - name
+    properties:
+      name:
+        type: string
+      url:
+        type: string
+        format: uri-reference
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Server:
+    type: object
+    required:
+      - url
+    properties:
+      url:
+        type: string
+      description:
+        type: string
+      variables:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/ServerVariable'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ServerVariable:
+    type: object
+    required:
+      - default
+    properties:
+      enum:
+        type: array
+        items:
+          type: string
+      default:
+        type: string
+      description:
+        type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Components:
+    type: object
+    properties:
+      schemas:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Schema'
+      responses:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Response'
+      parameters:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Parameter'
+      examples:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Example'
+      requestBodies:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/RequestBody'
+      headers:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Header'
+      securitySchemes:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/SecurityScheme'
+      links:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Link'
+      callbacks:
+        type: object
+        patternProperties:
+          '^[a-zA-Z0-9\.\-_]+$':
+            oneOf:
+              - $ref: '#/definitions/Reference'
+              - $ref: '#/definitions/Callback'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Schema:
+    type: object
+    properties:
+      title:
+        type: string
+      multipleOf:
+        type: number
+        minimum: 0
+        exclusiveMinimum: true
+      maximum:
+        type: number
+      exclusiveMaximum:
+        type: boolean
+        default: false
+      minimum:
+        type: number
+      exclusiveMinimum:
+        type: boolean
+        default: false
+      maxLength:
+        type: integer
+        minimum: 0
+      minLength:
+        type: integer
+        minimum: 0
+        default: 0
+      pattern:
+        type: string
+        format: regex
+      maxItems:
+        type: integer
+        minimum: 0
+      minItems:
+        type: integer
+        minimum: 0
+        default: 0
+      uniqueItems:
+        type: boolean
+        default: false
+      maxProperties:
+        type: integer
+        minimum: 0
+      minProperties:
+        type: integer
+        minimum: 0
+        default: 0
+      required:
+        type: array
+        items:
+          type: string
+        minItems: 1
+        uniqueItems: true
+      enum:
+        type: array
+        items: {}
+        minItems: 1
+        uniqueItems: false
+      type:
+        type: string
+        enum:
+          - array
+          - boolean
+          - integer
+          - number
+          - object
+          - string
+      not:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      allOf:
+        type: array
+        items:
+          oneOf:
+            - $ref: '#/definitions/Schema'
+            - $ref: '#/definitions/Reference'
+      oneOf:
+        type: array
+        items:
+          oneOf:
+            - $ref: '#/definitions/Schema'
+            - $ref: '#/definitions/Reference'
+      anyOf:
+        type: array
+        items:
+          oneOf:
+            - $ref: '#/definitions/Schema'
+            - $ref: '#/definitions/Reference'
+      items:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      properties:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Schema'
+            - $ref: '#/definitions/Reference'
+      additionalProperties:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+          - type: boolean
+        default: true
+      description:
+        type: string
+      format:
+        type: string
+      default: {}
+      nullable:
+        type: boolean
+        default: false
+      discriminator:
+        $ref: '#/definitions/Discriminator'
+      readOnly:
+        type: boolean
+        default: false
+      writeOnly:
+        type: boolean
+        default: false
+      example: {}
+      externalDocs:
+        $ref: '#/definitions/ExternalDocumentation'
+      deprecated:
+        type: boolean
+        default: false
+      xml:
+        $ref: '#/definitions/XML'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false        
+  
+  Discriminator:
+    type: object
+    required:
+      - propertyName
+    properties:
+      propertyName:
+        type: string
+      mapping:
+        type: object
+        additionalProperties:
+          type: string
+
+  XML:
+    type: object
+    properties:
+      name:
+        type: string
+      namespace:
+        type: string
+        format: uri
+      prefix:
+        type: string
+      attribute:
+        type: boolean
+        default: false
+      wrapped:
+        type: boolean
+        default: false
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Response:
+    type: object
+    required:
+      - description
+    properties:
+      description:
+        type: string
+      headers:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Header'
+            - $ref: '#/definitions/Reference'
+      content:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/MediaType'
+      links:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Link'
+            - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  MediaType:
+    oneOf:
+      - $ref: '#/definitions/MediaTypeWithExample'
+      - $ref: '#/definitions/MediaTypeWithExamples'
+
+  MediaTypeWithExample:
+    type: object
+    properties:
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      example: {}
+      encoding:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/Encoding'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false 
+
+  MediaTypeWithExamples:
+    type: object
+    required:
+      - examples
+    properties:
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Example'
+            - $ref: '#/definitions/Reference'
+      encoding:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/Encoding'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false 
+
+  Example:
+    type: object
+    properties:
+      summary:
+        type: string
+      description:
+        type: string
+      value: {}
+      externalValue:
+        type: string
+        format: uri-reference
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Header:
+    oneOf:
+      - $ref: '#/definitions/HeaderWithSchema'
+      - $ref: '#/definitions/HeaderWithContent'
+
+  HeaderWithSchema:
+    oneOf:
+      - $ref: '#/definitions/HeaderWithSchemaWithExample'
+      - $ref: '#/definitions/HeaderWithSchemaWithExamples'
+
+  HeaderWithSchemaWithExample:
+    type: object
+    required:
+      - schema
+    properties:
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - simple
+        default: simple
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      example: {}
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false  
+
+  HeaderWithSchemaWithExamples:
+    type: object
+    required:
+      - schema
+      - examples
+    properties:
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - simple
+        default: simple
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Example'
+            - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  HeaderWithContent:
+    type: object
+    required:
+      - content
+    properties:
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      content:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/MediaType'
+        minProperties: 1
+        maxProperties: 1
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Paths:
+    type: object
+    patternProperties:
+      '^\/': 
+        $ref: '#/definitions/PathItem'
+      '^x-': {}
+    additionalProperties: false
+
+  PathItem:
+    type: object
+    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'
+      parameters:
+        type: array
+        items:
+          oneOf:
+            - $ref: '#/definitions/Parameter'
+            - $ref: '#/definitions/Reference'
+        uniqueItems: true
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Operation:
+    type: object
+    required:
+      - responses
+    properties:
+      tags:
+        type: array
+        items:
+          type: string
+      summary:
+        type: string
+      description:
+        type: string
+      externalDocs:
+        $ref: '#/definitions/ExternalDocumentation'
+      operationId:
+        type: string
+      parameters:
+        type: array
+        items:
+          oneOf:
+            - $ref: '#/definitions/Parameter'
+            - $ref: '#/definitions/Reference'
+        uniqueItems: true
+      requestBody:
+        oneOf:
+          - $ref: '#/definitions/RequestBody'
+          - $ref: '#/definitions/Reference'
+      responses:
+        $ref: '#/definitions/Responses'
+      callbacks:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Callback'
+            - $ref: '#/definitions/Reference'
+      deprecated:
+        type: boolean
+        default: false
+      security:
+        type: array
+        items:
+          $ref: '#/definitions/SecurityRequirement'
+      servers:
+        type: array
+        items:
+          $ref: '#/definitions/Server'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Responses:
+    type: object
+    properties:
+      default:
+        oneOf:
+          - $ref: '#/definitions/Response'
+          - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^[1-5](?:\d{2}|XX)$':
+        oneOf:
+          - $ref: '#/definitions/Response'
+          - $ref: '#/definitions/Reference'
+      '^x-': {}
+    minProperties: 1
+    additionalProperties: false
+ 
+
+  SecurityRequirement:
+    type: object
+    additionalProperties:
+      type: array
+      items:
+        type: string
+
+  Tag:
+    type: object
+    required:
+      - name
+    properties:
+      name:
+        type: string
+      description:
+        type: string
+      externalDocs:
+        $ref: '#/definitions/ExternalDocumentation'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ExternalDocumentation:
+    type: object
+    required:
+      - url
+    properties:
+      description:
+        type: string
+      url:
+        type: string
+        format: uri-reference
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Parameter:
+    oneOf:
+      - $ref: '#/definitions/ParameterWithSchema'
+      - $ref: '#/definitions/ParameterWithContent'
+  
+  ParameterWithSchema:
+    oneOf:
+      - $ref: '#/definitions/ParameterWithSchemaWithExample'
+      - $ref: '#/definitions/ParameterWithSchemaWithExamples'
+
+  ParameterWithSchemaWithExample:
+    oneOf:
+      - $ref: '#/definitions/ParameterWithSchemaWithExampleInPath'
+      - $ref: '#/definitions/ParameterWithSchemaWithExampleInQuery'
+      - $ref: '#/definitions/ParameterWithSchemaWithExampleInHeader'
+      - $ref: '#/definitions/ParameterWithSchemaWithExampleInCookie'
+
+  ParameterWithSchemaWithExampleInPath:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+      - required
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - path
+      description:
+        type: string
+      required:
+        type: boolean
+        enum:
+          - true
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - matrix
+          - label
+          - simple
+        default: simple
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      example: {}
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ParameterWithSchemaWithExampleInQuery:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - query
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - form
+          - spaceDelimited
+          - pipeDelimited
+          - deepObject
+        default: form
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      example: {}
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false    
+
+  ParameterWithSchemaWithExampleInHeader:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - header
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - simple
+        default: simple
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      example: {}
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false    
+
+  ParameterWithSchemaWithExampleInCookie:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - cookie
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - form
+        default: form
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      example: {}
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false  
+
+  ParameterWithSchemaWithExamples:
+    oneOf:
+      - $ref: '#/definitions/ParameterWithSchemaWithExamplesInPath'
+      - $ref: '#/definitions/ParameterWithSchemaWithExamplesInQuery'
+      - $ref: '#/definitions/ParameterWithSchemaWithExamplesInHeader'
+      - $ref: '#/definitions/ParameterWithSchemaWithExamplesInCookie'
+
+  ParameterWithSchemaWithExamplesInPath:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+      - required
+      - examples
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - path
+      description:
+        type: string
+      required:
+        type: boolean
+        enum:
+          - true
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - matrix
+          - label
+          - simple
+        default: simple
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Example'
+            - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ParameterWithSchemaWithExamplesInQuery:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+      - examples
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - query
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - form
+          - spaceDelimited
+          - pipeDelimited
+          - deepObject
+        default: form
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Example'
+            - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false    
+
+  ParameterWithSchemaWithExamplesInHeader:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+      - examples
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - header
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - simple
+        default: simple
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Example'
+            - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false    
+
+  ParameterWithSchemaWithExamplesInCookie:
+    type: object
+    required:
+      - name
+      - in
+      - schema
+      - examples
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - cookie
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      style:
+        type: string
+        enum:
+          - form
+        default: form
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+      schema:
+        oneOf:
+          - $ref: '#/definitions/Schema'
+          - $ref: '#/definitions/Reference'
+      examples:
+        type: object
+        additionalProperties:
+          oneOf:
+            - $ref: '#/definitions/Example'
+            - $ref: '#/definitions/Reference'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ParameterWithContent:
+    oneOf:
+      - $ref: '#/definitions/ParameterWithContentInPath'
+      - $ref: '#/definitions/ParameterWithContentNotInPath'
+
+  ParameterWithContentInPath:
+    type: object
+    required:
+      - name
+      - in
+      - content
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - path
+      description:
+        type: string
+      required:
+        type: boolean
+        enum:
+          - true
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      content:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/MediaType'
+        minProperties: 1
+        maxProperties: 1
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ParameterWithContentNotInPath:
+    type: object
+    required:
+      - name
+      - in
+      - content
+    properties:
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - query
+          - header
+          - cookie
+      description:
+        type: string
+      required:
+        type: boolean
+        default: false
+      deprecated:
+        type: boolean
+        default: false
+      allowEmptyValue:
+        type: boolean
+        default: false
+      content:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/MediaType'
+        minProperties: 1
+        maxProperties: 1
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  RequestBody:
+    type: object
+    required:
+      - content
+    properties:
+      description:
+        type: string
+      content:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/MediaType'
+      required:
+        type: boolean
+        default: false
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  SecurityScheme:
+    oneOf:
+      - $ref: '#/definitions/APIKeySecurityScheme'
+      - $ref: '#/definitions/HTTPSecurityScheme'
+      - $ref: '#/definitions/OAuth2SecurityScheme'
+      - $ref: '#/definitions/OpenIdConnectSecurityScheme'
+  
+  APIKeySecurityScheme:
+    type: object
+    required:
+      - type
+      - name
+      - in
+    properties:
+      type:
+        type: string
+        enum:
+          - apiKey      
+      name:
+        type: string
+      in:
+        type: string
+        enum:
+          - header
+          - query
+          - cookie
+      description:
+        type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+  
+  HTTPSecurityScheme:
+    oneOf:
+      - $ref: '#/definitions/NonBearerHTTPSecurityScheme'
+      - $ref: '#/definitions/BearerHTTPSecurityScheme'
+
+  NonBearerHTTPSecurityScheme:
+    type: object
+    required:
+      - scheme
+      - type
+    properties:
+      scheme:
+        type: string
+        not:
+          enum:
+            - bearer
+      description:
+        type: string
+      type:
+        type: string
+        enum:
+          - http
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  BearerHTTPSecurityScheme:
+    type: object
+    required:
+      - type
+      - scheme
+    properties:
+      scheme:
+        type: string
+        enum:
+          - bearer
+      bearerFormat:
+        type: string
+      type:
+        type: string
+        enum:
+          - http
+      description:
+        type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  OAuth2SecurityScheme:
+    type: object
+    required:
+      - type
+      - flows
+    properties:
+      type:
+        type: string
+        enum:
+          - oauth2
+      flows:
+        $ref: '#/definitions/OAuthFlows'
+      description:
+        type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  OpenIdConnectSecurityScheme:
+    type: object
+    required:
+      - type
+      - openIdConnectUrl
+    properties:
+      type:
+        type: string
+        enum:
+          - openIdConnect      
+      openIdConnectUrl:
+        type: string
+        format: uri-reference
+      description:
+        type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  OAuthFlows:
+    type: object
+    properties:
+      implicit:
+        $ref: '#/definitions/ImplicitOAuthFlow'
+      password:
+        $ref: '#/definitions/PasswordOAuthFlow'
+      clientCredentials:
+        $ref: '#/definitions/ClientCredentialsFlow'
+      authorizationCode:
+        $ref: '#/definitions/AuthorizationCodeOAuthFlow'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ImplicitOAuthFlow:
+    type: object
+    required:
+      - authorizationUrl
+      - scopes
+    properties:
+      authorizationUrl:
+        type: string
+        format: uri-reference
+      refreshUrl:
+        type: string
+        format: uri-reference
+      scopes:
+        type: object
+        additionalProperties:
+          type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  PasswordOAuthFlow:
+    type: object
+    required:
+      - tokenUrl
+    properties:
+      tokenUrl:
+        type: string
+        format: uri-reference
+      refreshUrl:
+        type: string
+        format: uri-reference
+      scopes:
+        type: object
+        additionalProperties:
+          type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  ClientCredentialsFlow:
+    type: object
+    required:
+      - tokenUrl
+    properties:
+      tokenUrl:
+        type: string
+        format: uri-reference
+      refreshUrl:
+        type: string
+        format: uri-reference
+      scopes:
+        type: object
+        additionalProperties:
+          type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  AuthorizationCodeOAuthFlow:
+    type: object
+    required:
+      - authorizationUrl
+      - tokenUrl
+    properties:
+      authorizationUrl:
+        type: string
+        format: uri-reference
+      tokenUrl:
+        type: string
+        format: uri-reference
+      refreshUrl:
+        type: string
+        format: uri-reference
+      scopes:
+        type: object
+        additionalProperties:
+          type: string
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Link:
+    oneOf:
+      - $ref: '#/definitions/LinkWithOperationRef'
+      - $ref: '#/definitions/LinkWithOperationId'
+
+  LinkWithOperationRef:
+    type: object
+    properties:
+      operationRef:
+        type: string
+        format: uri-reference
+      parameters:
+        type: object
+        additionalProperties: {}
+      requestBody: {}
+      description:
+        type: string
+      server:
+        $ref: '#/definitions/Server'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  LinkWithOperationId:
+    type: object
+    properties:
+      operationId:
+        type: string
+      parameters:
+        type: object
+        additionalProperties: {}
+      requestBody: {}
+      description:
+        type: string
+      server:
+        $ref: '#/definitions/Server'
+    patternProperties:
+      '^x-': {}
+    additionalProperties: false
+
+  Callback:
+    type: object
+    additionalProperties:
+      $ref: '#/definitions/PathItem'
+    patternProperties:
+      '^x-': {}
+
+  Encoding:
+    type: object
+    properties:
+      contentType:
+        type: string
+      headers:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/Header'
+      style:
+        type: string
+        enum:
+          - form
+          - spaceDelimited
+          - pipeDelimited
+          - deepObject
+      explode:
+        type: boolean
+      allowReserved:
+        type: boolean
+        default: false
+    additionalProperties: false