From 0b487669089da214930892adecaeee687d2779fe Mon Sep 17 00:00:00 2001 From: its-me-yps Date: Mon, 8 Jan 2024 23:17:27 +0530 Subject: [PATCH 1/2] Intro and Getting Started section --- docs/dist.json | 5 +---- openapi/openapi.yaml | 23 +++++++++++++++++++---- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/dist.json b/docs/dist.json index baf2e1c..1bc4f8d 100644 --- a/docs/dist.json +++ b/docs/dist.json @@ -2,11 +2,8 @@ "openapi": "3.1.0", "info": { "title": "PuppyLove2.0_Backend", - "description": "API Documentation for PuppyLove2.0_Backend [Github](https://github.com/pclubiitk/puppylove2.0_backend)", + "description": "Programming Club is a community of IITK students who are highly enthusiastic about development, algorithms, security, ML, and all other aspects of programming. \n**Contact**: [WEBSITE](https://pclub.in/) \n# Introduction\n**PuppyLove** is a Dating App exclusively for IITK Campus. \nThis is an API Documentation for PuppyLove2.0_Backend [Github](https://github.com/pclubiitk/puppylove2.0_backend). \n* Please note that this documentation does not offer direct API services but rather serves as a descriptive resource detailing the endpoints and their usage. \n* If you're attempting to make requests to a live server or hosting your own instance of the PuppyLove2.0 application, please refer to this documentation for guide.\n# Getting Started\n* Explore the documentation to discover available endpoints and their usage.\n* Detailed JSON schemas are provided, outlining the structure required for both the data in POST requests and the expected formats for responses across all endpoints.\n* Endpoints are categorized into five sections based on their use case: Session, User, Admin, Fetch, Send, Verify. Note that an endpoint can belong to multiple sections.\n## Authentication\n* PuppyLove2.0 employs JWT (JSON Web Token) authentication.\n* During session login, a JWT is generated and sent back to the user via a cookie.\n* Subsequent requests require the inclusion of the JWT within the cookie header, which is authenticated by the Auth Middleware on server.\n* Each JWT remains valid for a single session only.\n* When using a web browser, the cookie header is managed automatically by the browser itself. However, for manual requests or when not using a browser-based environment, it's essential to retrieve the cookie from the login response. Subsequent requests must include this retrieved cookie within the headers to ensure proper authentication.\n", "version": "1.0.0", - "contact": { - "url": "https://pclub.in/" - }, "x-logo": { "url": "https://pclub.in/images/pclub.png" } diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index b92aa66..a804157 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1,12 +1,27 @@ openapi: 3.1.0 info: title: PuppyLove2.0_Backend - description: API Documentation for PuppyLove2.0_Backend [Github](https://github.com/pclubiitk/puppylove2.0_backend) + description: | + Programming Club is a community of IITK students who are highly enthusiastic about development, algorithms, security, ML, and all other aspects of programming. + **Contact**: [WEBSITE](https://pclub.in/) + # Introduction + **PuppyLove** is a Dating App exclusively for IITK Campus. + This is an API Documentation for PuppyLove2.0_Backend [Github](https://github.com/pclubiitk/puppylove2.0_backend). + * Please note that this documentation does not offer direct API services but rather serves as a descriptive resource detailing the endpoints and their usage. + * If you're attempting to make requests to a live server or hosting your own instance of the PuppyLove2.0 application, please refer to this documentation for guide. + # Getting Started + * Explore the documentation to discover available endpoints and their usage. + * Detailed JSON schemas are provided, outlining the structure required for both the data in POST requests and the expected formats for responses across all endpoints. + * Endpoints are categorized into five sections based on their use case: Session, User, Admin, Fetch, Send, Verify. Note that an endpoint can belong to multiple sections. + ## Authentication + * PuppyLove2.0 employs JWT (JSON Web Token) authentication. + * During session login, a JWT is generated and sent back to the user via a cookie. + * Subsequent requests require the inclusion of the JWT within the cookie header, which is authenticated by the Auth Middleware on server. + * Each JWT remains valid for a single session only. + * When using a web browser, the cookie header is managed automatically by the browser itself. However, for manual requests or when not using a browser-based environment, it's essential to retrieve the cookie from the login response. Subsequent requests must include this retrieved cookie within the headers to ensure proper authentication. version: 1.0.0 - contact: - url: https://pclub.in/ x-logo: - url: https://pclub.in/images/pclub.png + url: https://pclub.in/images/pclub.png tags: - name: Session From ba17e65453a37d6ebc1ccec7947baf8a3e2f62e9 Mon Sep 17 00:00:00 2001 From: its-me-yps Date: Mon, 8 Jan 2024 23:33:43 +0530 Subject: [PATCH 2/2] 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