- Install Node JS.
- Clone this repo and run
npm installin the repo root.
Starts the reference docs preview server.
Bundles the definition to the dist folder.
Validates the definition.
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 for more information.
- Navigate to the
openapi/components/schemasfolder. - Add a file named as you wish to name the schema.
- Define the schema.
- Refer to the schema using the
$ref(see example below).
This is a very simple schema example:
type: string description: The resource ID. Defaults to UUID v4 maxLength: 50 example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21This is a more complex schema example:
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 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:
defaultPaymentInstrument: $ref: ./PaymentInstrument.yamlThe value of the $ref is the path to the other schema definition.
You may use $refs to compose schema from other existing schema to avoid duplication.
You will use $refs to reference schema from your path definitions.
- Navigate to the
openapi/components/schemasfolder. - Open the file you wish to edit.
- Edit.
- Navigate to the
openapi/pathsfolder. - Add a new YAML file named like your URL endpoint except replacing
/with@and putting path parameters into curly braces like{example}. - Add the path and a ref to it inside of your
openapi.yamlfile inside of theopenapifolder.
Example addition to the openapi.yaml file:
'/customers/{id}': $ref: './paths/customers@{id}.yaml'Here is an example of a YAML file named customers@{id}.yaml in the paths folder:
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.phpYou'll see extensive usage of $refs in this example to different types of components including schemas.
You'll also notice $refs to code samples.
- Navigate to the
openapi/code_samplesfolder. - Navigate to the
<language>(e.g. PHP) sub-folder. - Navigate to the
pathfolder, 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.
