- Notifications
You must be signed in to change notification settings - Fork122
Redocly/openapi-starter
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
- InstallNode 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 toolsin the repository don't restrict you to anyspecific structure. Adjust the contribution guideto match your own structure. However, if youdon't have a structure in mind, this is agood place to start.
Update this contribution guide if youadjust the file/folder organization.
The.redocly.yaml controls settings for varioustools including the lint tool and the referencedocs engine. Open it to find examples andread the docsfor 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:stringdescription:The resource ID. Defaults to UUID v4maxLength:50example:4f6cf35x-2c4y-483z-a0a9-158621f77a21
This is a more complex schema example:
type:objectproperties:id:description:The customer identifier stringreadOnly:trueallOf: -$ref:./ResourceId.yamlwebsiteId:description:The website's IDallOf: -$ref:./ResourceId.yamlpaymentToken:type:stringwriteOnly:truedescription:| 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.yamlcreatedTime:description:The customer created timeallOf: -$ref:./ServerTimestamp.yamlupdatedTime:description:The customer updated timeallOf: -$ref:./ServerTimestamp.yamltags:description:A list of customer's tagsreadOnly:truetype:arrayitems:$ref:./Tags/Tag.yamlrevision: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:integerreadOnly:true_links:type:arraydescription:The links related to resourcereadOnly:trueminItems:3items:anyOf: -$ref:./Links/SelfLink.yaml -$ref:./Links/NotesLink.yaml -$ref:./Links/DefaultPaymentInstrumentLink.yaml -$ref:./Links/LeadSourceLink.yaml -$ref:./Links/WebsiteLink.yaml_embedded:type:arraydescription:>- Any embedded objects available that are requested by the `expand` querystring parameter.readOnly:trueminItems:1items:anyOf: -$ref:./Embeds/LeadSourceEmbed.yaml
If you have an JSON example, you can convert it to JSON schema using Redocly'sJSON to JSON schema tool.
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.yaml
The 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_(or whichever character you prefer) 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 theopenapi.yaml file:
'/customers/{id}':$ref:'./paths/customers_{id}.yaml'
Here is an example of a YAML file namedcustomers_{id}.yaml in thepaths folder:
get:tags: -Customerssummary:Retrieve a list of customersoperationId:GetCustomerCollectiondescription:| 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.yamlresponses:'200':description:A list of Customers was retrieved successfullyheaders:Rate-Limit-Limit:$ref:../components/headers/Rate-Limit-Limit.yamlRate-Limit-Remaining:$ref:../components/headers/Rate-Limit-Remaining.yamlRate-Limit-Reset:$ref:../components/headers/Rate-Limit-Reset.yamlPagination-Total:$ref:../components/headers/Pagination-Total.yamlPagination-Limit:$ref:../components/headers/Pagination-Limit.yamlPagination-Offset:$ref:../components/headers/Pagination-Offset.yamlcontent:application/json:schema:type:arrayitems:$ref:../components/schemas/Customer.yamltext/csv:schema:type:arrayitems:$ref:../components/schemas/Customer.yaml'401':$ref:../components/responses/AccessForbidden.yamlx-code-samples: -lang:PHPsource:$ref:../code_samples/PHP/customers/get.phppost:tags: -Customerssummary:Create a customer (without an ID)operationId:PostCustomerdescription:Another markdown description here.requestBody:$ref:../components/requestBodies/Customer.yamlresponses:'201':$ref:../components/responses/Customer.yaml'401':$ref:../components/responses/AccessForbidden.yaml'409':$ref:../components/responses/Conflict.yaml'422':$ref:../components/responses/InvalidDataError.yamlx-code-samples: -lang:PHPsource:$ref:../code_samples/PHP/customers/post.php
You'll see extensive usage of$refs in this example to different types of components including schemas.
You'll also notice$refs to code samples.
Automated code sample generations is enabled in the Redocly configuration file. Add manual code samples by the following process:
- 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 thecode_samples folder README.