From ba17e65453a37d6ebc1ccec7947baf8a3e2f62e9 Mon Sep 17 00:00:00 2001 From: its-me-yps Date: Mon, 8 Jan 2024 23:33:43 +0530 Subject: [PATCH] Local Doc server setup --- README.md | 289 ++++++------------------------------------------------ 1 file changed, 31 insertions(+), 258 deletions(-) diff --git a/README.md b/README.md index a8de8cd..6106208 100644 --- a/README.md +++ b/README.md @@ -1,258 +1,31 @@ -# 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 `` (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