Initial commit

.github/dependabot.yml

@@ -0,0 +1,14 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"
+    allow:
+      - dependency-name: "@redocly/cli"

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## What/Why/How?
+
+## Reference
+
+## Testing
+
+## Screenshots (optional)
+
+## Check yourself
+
+- [ ] Code is linted
+- [ ] Tested
+- [ ] All new/updated code is covered with tests
+
+## Security
+
+- [ ] Security impact of change has been considered
+- [ ] Code follows company security practices and guidelines

.gitignore

@@ -0,0 +1,3 @@
+# Dir for bundles
+dist
+node_modules

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.

docs/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>API Reference | ReDoc</title>
+    <!-- needed for adaptive design -->
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="icon" type="image/png" href="favicon.png">
+
+    <!--
+    ReDoc uses font options from the parent element
+    So override default browser styles
+    -->
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+    {{{redocHead}}}
+  </head>
+  <body>
+    {{{redocHTML}}}
+  </body>
+</html>

openapi/README.md

@@ -0,0 +1,13 @@
+## The `openapi` folder
+
+This folder contains your entrypoint `openapi.yaml`.
+
+That file contains references to the entire API definition.
+
+Here are some sections to pay attention to:
+
+* Top-level **description**: this accepts markdown, and Redoc and Redocly API Reference will render it at the top of the docs.  Consider maintaining your markdown in a separate file and [embedding it](https://redocly.com/docs/api-reference-docs/embedded-markdown/). Note to Redoc community edition users, the special tags are only available to the Redocly API Reference users, but you can still embed markdown.
+* Security schemes: you will define the scheme(s) your API uses for security (eg OAuth2, API Key, etc...). The security schemes are used by the Redocly API Reference "Try It" API console feature.
+* [Paths](paths/README.md): this defines each endpoint.  A path can have one operation per http method.
+* Tags: it's a good idea to organize each operation.  Each tag can have a description.  The description is used as a section description within the reference docs.
+* Servers: a list of your servers, each with a URL.

openapi/code_samples/C_sharp/echo/post.cs

@@ -0,0 +1,12 @@
+API.v1.Echo echo = new API.v1.Echo();
+echo.message = "Hello World!");
+EchoResponse response = echo.post();
+if (response.statusCode == HttpStatusCode.Created)
+{
+  // Success
+}
+else
+{
+  // Something wrong -- check response for errors
+  Console.WriteLine(response.getRawResponse());
+}

openapi/code_samples/PHP/echo/post.php

@@ -0,0 +1,7 @@
+$form = new \API\Entities\Echo();
+$form->setMessage("Hello World!");
+try {
+    $pet = $client->echo()->post($form);
+} catch (UnprocessableEntityException $e) {
+    var_dump($e->getErrors());
+}

openapi/code_samples/README.md

@@ -0,0 +1,11 @@
+Code samples
+=====
+
+This is our recommended convention for organizing `code_samples`:
+
+[x-codeSamples](https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples/)
+Path `<lang>/<path>/<HTTP verb>.<extension>` where:
+  * `<lang>` - name of the language from [this](https://github.com/github-linguist/linguist/blob/master/lib/linguist/popular.yml) list.
+  * `<path>` - path of the target method, where all `/` are replaced with `_`.
+  * `<HTTP verb>` - verb of target method.
+  * `<extension>` - ignored.