Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/redocly/openapi-starter
OpenAPI starter repository
https://github.com/redocly/openapi-starter
api-reference boilerplate openapi openapi3 openapi31 swagger template
Last synced: 3 days ago
JSON representation
OpenAPI starter repository
- Host: GitHub
- URL: https://github.com/redocly/openapi-starter
- Owner: Redocly
- License: mit
- Created: 2020-09-10T15:11:31.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-25T14:41:10.000Z (2 months ago)
- Last Synced: 2024-10-30T00:46:52.618Z (about 2 months ago)
- Topics: api-reference, boilerplate, openapi, openapi3, openapi31, swagger, template
- Language: C#
- Homepage:
- Size: 223 KB
- Stars: 160
- Watchers: 18
- Forks: 115
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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 `` (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.