You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
255 lines
7.0 KiB
255 lines
7.0 KiB
# Mieux Voter OpenAPI Definition
|
|
|
|
TODO:
|
|
CI on Jenkins
|
|
|
|
|
|
## 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://docs.redoc.ly/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
|
|
|
|
```
|
|
|
|
##### 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 `@` 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
|
|
|
|
1. Navigate to the `openapi/code_samples` folder.
|
|
2. Navigate to the `<language>` (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.
|