# Contributing

We welcome all contributions and will work with you to get them incorporated if possible. Below are some guidelines on how to go about making changes.

# Locally Running and Testing

In order to get a local copy of the docs running on your machine, you can follow the below steps (you'll need yarn installed):

git clone https://github.com/thinkst/canarytools-docs.git

cd canarytools-docs

yarn install

yarn docs:dev

1
2
3
4
5
6
7

# Markdown

Most of the work is done in some form of Markdown. Altering / fixing / adding paragraphs should be simple enough if you know Markdown (otherwise you can take a look at this nifty Cheat-sheet (opens new window)).

Vuepress has some pre-defined custom containers that you can read up on here (opens new window).

We include some of our own custom containers, at this point we've only added api-response which can be included using something similar to (remove the leading \ from the lines):

::: api-response

\```json
{
    'result': 'success'
}
\```
:::

1
2
3
4
5
6
7
8

# Endpoints

Endpoints are defined as YAML at the top of the file.

---
endpoints:
  example:
    name: Example Endpoint
    url: /api/v1/example
    method: GET
    description: Example endpoint to show the YAML format
    params:
      - name: auth_token
        required: true
        type: string
        description: A valid auth token
      - name: another_param
        required: false
        type: boolean
        description:  An example param
    response: A JSON structure with result indicator.
---

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

These will be generated into content on the page using APIEndpoints and APIDetails.

A param can include additional properties that will further enhance the information around it:

- name: example_param
  required: true | false
  type: string | int | boolean
  default: 10 | "'a string'" (can ignore if no default)
  deprecated: true | false (can ignore and default to false)
  deprecated_message: "An optional deprecated message to show if deprecated" (can ignore if not deprecated)
  description: An example description

1
2
3
4
5
6
7

# APIEndpoints

This will generate the introduction to the page, including a list of all endpoints.

slot details will generate the description for the page alongside the endpoint list.

<APIEndpoints :endpoints="$page.frontmatter.endpoints" :path="$page.regularPath">

::::: slot details

...

:::::

</APIEndpoints>

1
2
3
4
5
6
7
8
9

# APIDetails

This will generate the endpoint details section.

slot example will generate the example + response section
slot description will allow you to overwrite the description defined in the endpoint YAML
slot required-parameters-notes will allow you to add notes under the required parameters section
slot optional-parameters-notes will allow you to add notes under the optional parameters section
slot response will allow you to overwrite the response defined in the endpoint YAML


<APIDetails :endpoint="$page.frontmatter.endpoints.example">

::::: slot example

...

:::::

</APIDetails>

1
2
3
4
5
6
7
8
9
10