[IGNORE] Technical comparison

.gitignore

@@ -4,3 +4,5 @@ _site/
 _pdf
 .DS_Store
 .idea
+node_modules
+.env

.redocly.yaml

@@ -0,0 +1,28 @@
+# See https://redocly.com/docs/cli/configuration/ for more information.
+apis:
+  sample@v1:
+    root: ./openapi/openapi.yaml
+  sample@v2:
+    root: ./openapi/openapi-2.yaml
+versionPicker:
+  showForUnversioned: true
+lint:
+  extends:
+    - recommended
+  rules:
+    no-unused-components: error
+pagination: none
+features.openapi:
+  showConsole: true
+  htmlTemplate: ./docs/index.html
+  theme:
+    colors:
+      primary:
+        main: "#32329f"
+  generateCodeSamples:
+    languages:  # Array of language config objects; indicates in which languages to generate code samples.
+      - lang: curl
+      - lang: Node.js
+      - lang: JavaScript
+      - lang: PHP
+      - lang: Python

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ivan Goncharov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,258 @@
+# OpenAPI Definition Starter
+
+## How to use this starter
+
+![Click use template button](https://user-images.githubusercontent.com/3975738/92927304-12e35d80-f446-11ea-9bd3-a0f8a69792d0.png)
+
+## Working on your OpenAPI Definition
+
+### Install
+
+1. Install [Node JS](https://nodejs.org/).
+2. Clone this repo and run `npm install` in the repo root.
+
+### Usage
+
+#### `npm start`
+Starts the reference docs preview server.
+
+#### `npm run build`
+Bundles the definition to the dist folder.
+
+#### `npm test`
+Validates the definition.
+
+## Contribution Guide
+
+Below is a sample contribution guide. The tools
+in the repository don't restrict you to any
+specific structure. Adjust the contribution guide
+to match your own structure. However, if you
+don't have a structure in mind, this is a
+good place to start.
+
+Update this contribution guide if you
+adjust the file/folder organization.
+
+The `.redocly.yaml` controls settings for various
+tools including the lint tool and the reference
+docs engine.  Open it to find examples and
+[read the docs](https://redocly.com/docs/cli/configuration/)
+for more information.
+
+
+### Schemas
+
+#### Adding Schemas
+
+1. Navigate to the `openapi/components/schemas` folder.
+2. Add a file named as you wish to name the schema.
+3. Define the schema.
+4. Refer to the schema using the `$ref` (see example below).
+
+##### Example Schema
+This is a very simple schema example:
+```yaml
+type: string
+description: The resource ID. Defaults to UUID v4
+maxLength: 50
+example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
+```
+This is a more complex schema example:
+```yaml
+type: object
+properties:
+  id:
+    description: The customer identifier string
+    readOnly: true
+    allOf:
+      - $ref: ./ResourceId.yaml
+  websiteId:
+    description: The website's ID
+    allOf:
+      - $ref: ./ResourceId.yaml
+  paymentToken:
+    type: string
+    writeOnly: true
+    description: |
+      A write-only payment token; if supplied, it will be converted into a
+      payment instrument and be set as the `defaultPaymentInstrument`. The
+      value of this property will override the `defaultPaymentInstrument`
+      in the case that both are supplied. The token may only be used once
+      before it is expired.
+  defaultPaymentInstrument:
+    $ref: ./PaymentInstrument.yaml
+  createdTime:
+    description: The customer created time
+    allOf:
+      - $ref: ./ServerTimestamp.yaml
+  updatedTime:
+    description: The customer updated time
+    allOf:
+      - $ref: ./ServerTimestamp.yaml
+  tags:
+    description: A list of customer's tags
+    readOnly: true
+    type: array
+    items:
+      $ref: ./Tags/Tag.yaml
+  revision:
+    description: >
+      The number of times the customer data has been modified.
+
+      The revision is useful when analyzing webhook data to determine if the
+      change takes precedence over the current representation.
+    type: integer
+    readOnly: true
+  _links:
+    type: array
+    description: The links related to resource
+    readOnly: true
+    minItems: 3
+    items:
+      anyOf:
+        - $ref: ./Links/SelfLink.yaml
+        - $ref: ./Links/NotesLink.yaml
+        - $ref: ./Links/DefaultPaymentInstrumentLink.yaml
+        - $ref: ./Links/LeadSourceLink.yaml
+        - $ref: ./Links/WebsiteLink.yaml
+  _embedded:
+    type: array
+    description: >-
+      Any embedded objects available that are requested by the `expand`
+      querystring parameter.
+    readOnly: true
+    minItems: 1
+    items:
+      anyOf:
+        - $ref: ./Embeds/LeadSourceEmbed.yaml
+
+```
+
+If you have an JSON example, you can convert it to JSON schema using Redocly's [JSON to JSON schema tool](https://redocly.com/tools/json-to-json-schema/).
+
+##### Using the `$ref`
+
+Notice in the complex example above the schema definition itself has `$ref` links to other schemas defined.
+
+Here is a small excerpt with an example:
+
+```yaml
+defaultPaymentInstrument:
+  $ref: ./PaymentInstrument.yaml
+```
+
+The value of the `$ref` is the path to the other schema definition.
+
+You may use `$ref`s to compose schema from other existing schema to avoid duplication.
+
+You will use `$ref`s to reference schema from your path definitions.
+
+#### Editing Schemas
+
+1. Navigate to the `openapi/components/schemas` folder.
+2. Open the file you wish to edit.
+3. Edit.
+
+### Paths
+
+#### Adding a Path
+
+1. Navigate to the `openapi/paths` folder.
+2. Add a new YAML file named like your URL endpoint except replacing `/` with `_` (or whichever character you prefer) and putting path parameters into curly braces like `{example}`.
+3. Add the path and a ref to it inside of your `openapi.yaml` file inside of the `openapi` folder.
+
+Example addition to the `openapi.yaml` file:
+```yaml
+'/customers/{id}':
+  $ref: './paths/customers_{id}.yaml'
+```
+
+Here is an example of a YAML file named `customers_{id}.yaml` in the `paths` folder:
+
+```yaml
+get:
+  tags:
+    - Customers
+  summary: Retrieve a list of customers
+  operationId: GetCustomerCollection
+  description: |
+    You can have a markdown description here.
+  parameters:
+    - $ref: ../components/parameters/collectionLimit.yaml
+    - $ref: ../components/parameters/collectionOffset.yaml
+    - $ref: ../components/parameters/collectionFilter.yaml
+    - $ref: ../components/parameters/collectionQuery.yaml
+    - $ref: ../components/parameters/collectionExpand.yaml
+    - $ref: ../components/parameters/collectionFields.yaml
+  responses:
+    '200':
+      description: A list of Customers was retrieved successfully
+      headers:
+        Rate-Limit-Limit:
+          $ref: ../components/headers/Rate-Limit-Limit.yaml
+        Rate-Limit-Remaining:
+          $ref: ../components/headers/Rate-Limit-Remaining.yaml
+        Rate-Limit-Reset:
+          $ref: ../components/headers/Rate-Limit-Reset.yaml
+        Pagination-Total:
+          $ref: ../components/headers/Pagination-Total.yaml
+        Pagination-Limit:
+          $ref: ../components/headers/Pagination-Limit.yaml
+        Pagination-Offset:
+          $ref: ../components/headers/Pagination-Offset.yaml
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: ../components/schemas/Customer.yaml
+        text/csv:
+          schema:
+            type: array
+            items:
+              $ref: ../components/schemas/Customer.yaml
+    '401':
+      $ref: ../components/responses/AccessForbidden.yaml
+  x-code-samples:
+    - lang: PHP
+      source:
+        $ref: ../code_samples/PHP/customers/get.php
+post:
+  tags:
+    - Customers
+  summary: Create a customer (without an ID)
+  operationId: PostCustomer
+  description: Another markdown description here.
+  requestBody:
+    $ref: ../components/requestBodies/Customer.yaml
+  responses:
+    '201':
+      $ref: ../components/responses/Customer.yaml
+    '401':
+      $ref: ../components/responses/AccessForbidden.yaml
+    '409':
+      $ref: ../components/responses/Conflict.yaml
+    '422':
+      $ref: ../components/responses/InvalidDataError.yaml
+  x-code-samples:
+    - lang: PHP
+      source:
+        $ref: ../code_samples/PHP/customers/post.php
+```
+
+You'll see extensive usage of `$ref`s in this example to different types of components including schemas.
+
+You'll also notice `$ref`s to code samples.
+
+### Code samples
+
+Automated code sample generations is enabled in the Redocly configuration file. Add manual code samples by the following process:
+
+1. Navigate to the `openapi/code_samples` folder.
+2. Navigate to the `<language>` (e.g. PHP) sub-folder.
+3. Navigate to the `path` folder, and add ref to the code sample.
+
+You can add languages by adding new folders at the appropriate path level.
+
+More details inside the `code_samples` folder README.