-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2 from its-me-yps/main
Intro and Getting Started Section
- Loading branch information
Showing
3 changed files
with
51 additions
and
266 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,258 +1,31 @@ | ||
| # OpenAPI Definition Starter | ||
|
|
||
| ## How to use this starter | ||
|
|
||
|  | ||
|
|
||
| ## 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. | ||
| # Local Doc Server Setup Guide | ||
|
|
||
| ## Local Setup | ||
|
|
||
| 1. **Clone the Repository** | ||
|
|
||
| 2. **Install Dependencies** | ||
| ```bash | ||
| npm install | ||
| ``` | ||
| 3. **Start the Documentation Server** | ||
| ```bash | ||
| npm start | ||
| ``` | ||
| The server will start at `http://127.0.0.1:8080` | ||
|
|
||
| ## Making Changes | ||
| 1. **Install Redocly CLI** | ||
| ```bash | ||
| npm i -g @redocly/cli@latest | ||
| ``` | ||
| 2. **Modify OpenAPI Files** | ||
| Make required changes to the files located in the `openapi/` directory. | ||
| 3. **Update dist.json** | ||
| ```bash | ||
| cd docs | ||
| redocly bundle ../openapi/openapi.yaml -o dist.json | ||
| ``` | ||
| 4. **Running the Updated Server** | ||
| ```bash | ||
| npm start |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters