From f9bba30439cc4bb7bc24bff90effba7ab4acf6cf Mon Sep 17 00:00:00 2001
From: David Biesack <David.Biesack@apiture.com>
Date: Fri, 29 Jan 2021 14:06:43 -0500
Subject: [PATCH] add swaggerplusplus extensions

---
 _extensions/swaggerplusplus-x-anyOf.md        | 28 +++++++++++++++
 _extensions/swaggerplusplus-x-callbacks.md    | 34 +++++++++++++++++++
 _extensions/swaggerplusplus-x-deprecated.md   | 29 ++++++++++++++++
 _extensions/swaggerplusplus-x-description.md  | 24 +++++++++++++
 .../swaggerplusplus-x-discriminator.md        | 30 ++++++++++++++++
 _extensions/swaggerplusplus-x-links.md        | 30 ++++++++++++++++
 _extensions/swaggerplusplus-x-not.md          | 26 ++++++++++++++
 _extensions/swaggerplusplus-x-nullable.md     | 31 +++++++++++++++++
 _extensions/swaggerplusplus-x-oneOf.md        | 28 +++++++++++++++
 _extensions/swaggerplusplus-x-required.md     | 27 +++++++++++++++
 _extensions/swaggerplusplus-x-servers.md      | 30 ++++++++++++++++
 _extensions/swaggerplusplus-x-summary.md      | 24 +++++++++++++
 _extensions/swaggerplusplus-x-trace.md        | 27 +++++++++++++++
 13 files changed, 368 insertions(+)
 create mode 100644 _extensions/swaggerplusplus-x-anyOf.md
 create mode 100644 _extensions/swaggerplusplus-x-callbacks.md
 create mode 100644 _extensions/swaggerplusplus-x-deprecated.md
 create mode 100644 _extensions/swaggerplusplus-x-description.md
 create mode 100644 _extensions/swaggerplusplus-x-discriminator.md
 create mode 100644 _extensions/swaggerplusplus-x-links.md
 create mode 100644 _extensions/swaggerplusplus-x-not.md
 create mode 100644 _extensions/swaggerplusplus-x-nullable.md
 create mode 100644 _extensions/swaggerplusplus-x-oneOf.md
 create mode 100644 _extensions/swaggerplusplus-x-required.md
 create mode 100644 _extensions/swaggerplusplus-x-servers.md
 create mode 100644 _extensions/swaggerplusplus-x-summary.md
 create mode 100644 _extensions/swaggerplusplus-x-trace.md

diff --git a/_extensions/swaggerplusplus-x-anyOf.md b/_extensions/swaggerplusplus-x-anyOf.md
new file mode 100644
index 000000000..c470153ee
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-anyOf.md
@@ -0,0 +1,28 @@
+---
+name: Swaggerplus JSON Schema anyOf
+slug: swaggerplusplus-anyOf
+property: x-anyOf
+description: >-
+  Add to a Schema Object in an OpenAPI 2.0 API description document to use newer `anyOf` JSON Schema constructs.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  components:
+    schemas:
+      x-anyOf:
+        - schemaObject1: {}
+        - schemaObject2: {}
+        - schemaObject3: {}
+        - ...
+tags:
+  - Migration
+  - JSON Schema
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-callbacks.md b/_extensions/swaggerplusplus-x-callbacks.md
new file mode 100644
index 000000000..48dc21b89
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-callbacks.md
@@ -0,0 +1,34 @@
+---
+name: Swaggerplus Callbacks
+slug: swaggerplusplus-callbacks
+property: x-callbacks
+description: >-
+  Define OpenAPI 3.x `callbacks` [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callback-object) operation
+  elements in an OpenAPI 2.0 API description document.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  callbacks:
+    myCallback1:
+      'http://callback.example.com?transactionId={$request.body#/id}&email={$request.body#/email}':
+        post:
+          requestBody:
+            description: Callback payload
+            content:
+              'application/json':
+                schema:
+                  $ref: '#/components/schemas/callback1Payload'
+          responses:
+            '200':
+              description: Callback successfully processed and no retries will be performed
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-deprecated.md b/_extensions/swaggerplusplus-x-deprecated.md
new file mode 100644
index 000000000..f1bf8e859
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-deprecated.md
@@ -0,0 +1,29 @@
+---
+name: Swaggerplus Deprecated
+slug: swaggerplusplus-deprecated
+property: x-deprecated
+description: >-
+  Mark OpenAPI 3.x elements as `deprecated` [label](url) in an OpenAPI 2.0 API description document.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+components
+  parameters:
+    bookIdPathParam:
+      - name: bookId
+        in: path
+        schema:
+          type: string
+        desccription: The ID of a book.
+        x-deprecated: true
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-description.md b/_extensions/swaggerplusplus-x-description.md
new file mode 100644
index 000000000..57752166b
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-description.md
@@ -0,0 +1,24 @@
+---
+name: Swaggerplus Description
+slug: swaggerplusplus-description
+property: x-description
+description: >-
+  Add a OpenAPI 3.x `description` to elements such as path items in an OpenAPI 2.0 API description document
+  where `description` is not allowed.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  paths:
+    "/books":
+      x-description: This resource is a collection of books.
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-discriminator.md b/_extensions/swaggerplusplus-x-discriminator.md
new file mode 100644
index 000000000..8adeaf217
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-discriminator.md
@@ -0,0 +1,30 @@
+---
+name: Swaggerplus JSON Schema discriminator
+slug: swaggerplusplus-discriminator
+property: x-discriminator
+description: >-
+  Add to an Schema Object in an OpenAPI 2.0 API description document to use OAS 3.0 `discriminator` JSON Schema constructs.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  components:
+    schemas:
+      publication:
+        x-oneOf:
+          - '#/definitions/book'
+          - '#/definitions/magazine'
+          - '#/definitions/newspaper'
+        x-discriminator:
+          propertyName: publicationType
+tags:
+  - Migration
+  - JSON Schema
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-links.md b/_extensions/swaggerplusplus-x-links.md
new file mode 100644
index 000000000..382c53d83
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-links.md
@@ -0,0 +1,30 @@
+---
+name: Swaggerplus Liks
+slug: swaggerplusplus-links
+property: x-link
+description: >-
+  Define OpenAPI 3.x `links` [{Link Object}](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#link-object) map
+  an OpenAPI 2.0 API [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#response-object).
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  info: ...
+  host: https://api.gigantic-server.com/v1
+  x-servers:
+    - url: https://development.gigantic-server.com/v1
+      description: Development server
+    - url: https://staging.gigantic-server.com/v1
+      description: Staging server
+    - url: https://api.gigantic-server.com/v1
+      description: Production server
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-not.md b/_extensions/swaggerplusplus-x-not.md
new file mode 100644
index 000000000..72eca8a7b
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-not.md
@@ -0,0 +1,26 @@
+---
+name: Swaggerplus JSON Schema Not
+slug: swaggerplusplus-not
+property: x-not
+description: >-
+  Add to a Schema Object in an OpenAPI 2.0 API description document to use newer `not` JSON Schema constructs.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  components:
+    schemas:
+      book:
+        x-not:
+          schemaObject
+tags:
+  - Migration
+  - JSON Schema
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-nullable.md b/_extensions/swaggerplusplus-x-nullable.md
new file mode 100644
index 000000000..e2c699208
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-nullable.md
@@ -0,0 +1,31 @@
+---
+name: Swaggerplus JSON Schema Nullable
+slug: swaggerplusplus-nullable
+property: x-nullable
+description: >-
+  Add to a Schema Object in an OpenAPI 2.0 API description document to use the `nullable` JSON Schema construct.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  components:
+    schemas:
+      book:
+        title: Book
+        description: Representation of a published book.
+        properties:
+          title:
+            nullable: false
+            schema:
+              type: string
+tags:
+  - Migration
+  - JSON Schema
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-oneOf.md b/_extensions/swaggerplusplus-x-oneOf.md
new file mode 100644
index 000000000..b0c35fb31
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-oneOf.md
@@ -0,0 +1,28 @@
+---
+name: Swaggerplus JSON Schema oneOf
+slug: swaggerplusplus-oneOf
+property: x-oneOf
+description: >-
+  Add to a Schema Object in an OpenAPI 2.0 API description document to use newer `oneOf` JSON Schema constructs.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  components:
+    schemas:
+      x-oneOf:
+        - schemaObject1: {}
+        - schemaObject2: {}
+        - schemaObject3: {}
+        - ....
+tags:
+  - Migration
+  - JSON Schema
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-required.md b/_extensions/swaggerplusplus-x-required.md
new file mode 100644
index 000000000..1c5770550
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-required.md
@@ -0,0 +1,27 @@
+---
+name: Swaggerplus JSON Schema Required
+slug: swaggerplusplus-required
+property: x-required
+description: >-
+  Lists properties that were removed from a Schema Object's `required` array when
+  the `swaggerplusplus` tool processed `x-anyOf`, `x-oneOf` or `x-not` schema constructs.
+example:
+  components:
+    schemas:
+      book:
+        x-required:
+          - title
+          - authors
+tags:
+  - Migration
+  - JSON Schema
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-servers.md b/_extensions/swaggerplusplus-x-servers.md
new file mode 100644
index 000000000..1379dd43e
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-servers.md
@@ -0,0 +1,30 @@
+---
+name: Swaggerplus Servers
+slug: swaggerplusplus-servers
+property: x-servers
+description: >-
+  Define OpenAPI 3.x `servers` [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#server-object)
+  elements in an OpenAPI 2.0 API description document.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  info: ...
+  host: https://api.gigantic-server.com/v1
+  x-servers:
+    - url: https://development.gigantic-server.com/v1
+      description: Development server
+    - url: https://staging.gigantic-server.com/v1
+      description: Staging server
+    - url: https://api.gigantic-server.com/v1
+      description: Production server
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-summary.md b/_extensions/swaggerplusplus-x-summary.md
new file mode 100644
index 000000000..0e0e62de0
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-summary.md
@@ -0,0 +1,24 @@
+---
+name: Swaggerplus Summary
+slug: swaggerplusplus-ummary
+property: x-summary
+description: >-
+  Add a OpenAPI 3.x `summary` to elements an OpenAPI 2.0 API description document
+  where `summary` is not allowed.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  paths:
+    "/books":
+      x-summary: This resource is a collection of books.
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...
diff --git a/_extensions/swaggerplusplus-x-trace.md b/_extensions/swaggerplusplus-x-trace.md
new file mode 100644
index 000000000..e1749b177
--- /dev/null
+++ b/_extensions/swaggerplusplus-x-trace.md
@@ -0,0 +1,27 @@
+---
+name: Swaggerplus Trace
+slug: swaggerplusplus-trace
+property: x-trace
+description: >-
+  Define OpenAPI 3.x `trace` [Path Iem](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject) operation
+  elements in an OpenAPI 2.0 API description document.
+  This allows converting OpenAPI 2.0 to OpenAPI 3.0 for tools which work with OpenAPI 3.0.
+example:
+  paths:
+    /books:
+      x-trace:
+        operationId: books-trace
+        desription: The TRACE HTTP operation for the books resource.
+        responses: ...
+tags:
+  - Migration
+created: "2021-01-29"
+modified: "2021-01-29"
+url: https://raw.githubusercontent.com/api-specification-toolbox/toolbox/main/_extensions/
+specificationVersion: "0.14"
+apis: []
+include: []
+x-common:
+  - type: x-website
+    url: https://github.com/Mermade/swaggerplusplus
+...