Boats utils

Collection of useful boats template helpers to be used with j-d-carmichael/boats.

Table of Contents generated with DocToc

• Usage
• Modules
  • extend
    • Examples
  • database-entry
    • Examples
  • pagination
    • Examples

Usage

1npm install @acrontum/boats-utils

In your openapi boats project, simply include this module as a helper in your build command:

1{
2  "name": "service-openapi-spec",
3  "version": "1.0.0",
4  "description": "Some boats openapi builder",
5  "scripts": {
6    "prebuild": "rm -rf build",
7    "build": "NODE_ENV=test boats --yes -f node_modules/@acrontum/boats-utils/dist -i ./src/index.yml -o ./build/api.yml",
8    "postbuild": "cp build/api*.yml ./release/$npm_package_name.yml"
9  },
10  "keywords": [],
11  "author": "p-mcgowan",
12  "devDependencies": {
13    "boats": "^2.25.0",
14    "@acrontum/boats-utils": "^1.0.0"
15  }
16}

Modules

extend

Extend a base model with additional, omitted, required, and / or optional fields.

1# model.yml
2
3type: object
4properties:
5  id:
6    type: string
7    format: uuid
8  name:
9    type: string
10  email:
11    type: string
12    format: email
13  profilePicture:
14    type: string
15    format: uri
16  # ...

1# postModel.yml
2
3{{
4  extend('./model.yml', {
5    omit: [
6      'properties.id'
7    ],
8    require: [
9      'properties.name',
10      'properties.email'
11    ],
12    include: [
13      ['properties.username', { type: 'string', 'x-unique': true }]
14    ],
15    optional: [
16      'properties.dateOfBirth'
17    ]
18  })
19}}

Examples

---

Removing fields from the model:

1# model.yml
2
3type: object
4required:
5  - id
6properties:
7  id:
8    type: string
9    format: uuid
10  createdAt:
11    type: string
12    format: date-time
13  updatedAt:
14    type: string
15    format: date-time
16  name:
17    type: string
18  email:
19    type: string
20    format: email
21  profilePicture:
22    type: string
23    format: uri

1# postModel.yml
2
3{{
4  extend('./model.yml', {
5    omit: [
6      'properties.id',
7      'properties.createdAt',
8      'properties.updatedAt'
9    ]
10  })
11}}

Would output:

1type: object
2properties:
3  name:
4    type: string
5  email:
6    type: string
7    format: email
8  profilePicture:
9    type: string
10    format: uri

---

Adding fields to the model:

1# model.yml
2
3type: object
4properties:
5  name:
6    type: string
7  email:
8    type: string
9    format: email
10  profilePicture:
11    type: string
12    format: uri

1# postModel.yml
2{{
3  extend('./model.yml', {
4    include: [
5      ['properties.password', { type: 'string', minLength: 32 }]
6    ]
7  })
8}}

Would output:

1type: object
2properties:
3  name:
4    type: string
5  email:
6    type: string
7    format: email
8  profilePicture:
9    type: string
10    format: uri
11  password:
12    type: string
13    minLength: 32

---

Marking fields as required:

1# model.yml
2
3type: object
4properties:
5  name:
6    type: string
7  email:
8    type: string
9    format: email
10  profilePicture:
11    type: string
12    format: uri

1# postModel.yml
2
3{{
4  extend('./model.yml', {
5    require: [
6      'properties.email',
7      'properties.name'
8    ]
9  })
10}}

Would output:

1type: object
2required:
3  - name
4  - email
5properties:
6  name:
7    type: string
8  email:
9    type: string
10    format: email
11  profilePicture:
12    type: string
13    format: uri

---

Marking fields as optional:

1# model.yml
2
3type: object
4require:
5  - name
6  - email
7  - profilePicture
8properties:
9  name:
10    type: string
11  email:
12    type: string
13    format: email
14  profilePicture:
15    type: string
16    format: uri

1# postModel.yml
2
3{{
4  extend('./model.yml', {
5    optional: [
6      'properties.profilePicture'
7    ]
8  })
9}}

Would output:

1type: object
2required:
3  - name
4  - email
5properties:
6  name:
7    type: string
8  email:
9    type: string
10    format: email
11  profilePicture:
12    type: string
13    format: uri

---

database-entry

Adds common DB fields to a model.

1type: object
2properties:
3  {{ databaseentry(<options>) }}
4  otherProps:
5    type: string
6  # ...

Examples

---

With no params:

1# model.yml
2
3type: object
4properties:
5  {{ databaseentry() }}
6  name:
7    type: string
8  profilePicture:
9    type: string
10    format: uri

Would output:

1type: object
2properties:
3  id:
4    type: string
5    format: uuid
6  createdAt:
7    type: string
8    format: date-time
9  updatedAt:
10    type: string
11    format: date-time
12  name:
13    type: string
14  profilePicture:
15    type: string

---

To specifiy the id type:

1# model.yml
2
3type: object
4properties:
5  {{ databaseentry({ id: 'string' }) }}
6# {{ databaseentry({ id: 'number' }) }}
7  name:
8    type: string
9  profilePicture:
10    type: string
11    format: uri

Would output:

1type: object
2properties:
3  id:
4    type: string
5#   type: number
6  createdAt:
7    type: string
8    format: date-time
9  updatedAt:
10    type: string
11    format: date-time
12  name:
13    type: string
14  profilePicture:
15    type: string

---

With softDeletion:

1# model.yml
2
3type: object
4properties:
5  {{ databaseentry({ softDeletion: true }) }}
6  name:
7    type: string
8  profilePicture:
9    type: string
10    format: uri

Would output:

1type: object
2properties:
3  id:
4    type: string
5    format: uuid
6  createdAt:
7    type: string
8    format: date-time
9  updatedAt:
10    type: string
11    format: date-time
12  deletedAt:
13    type: string
14    format: date-time
15  name:
16    type: string
17  profilePicture:
18    type: string

pagination

Adds a collection-type pagination model.

1{{ pagination(<path_or_options>) }}

Examples

---

With no params:

1# components/schemas/user/model.yml
2
3type: object
4properties:
5  name:
6    type: string
7  numberOfDogs:
8    type: number

1# components/schemas/user/models.yml
2
3{{ pagination() }}

Would output:

1type: object
2required:
3  - meta
4  - data
5properties:
6  meta:
7    $ref: "#/components/schemas/Meta"
8  data:
9    type: array
10    items: 
11      $ref: "./model.yml"

---

To specify another model name:

1# components/schemas/user/singleUserResponse.yml
2
3type: object
4properties:
5  name:
6    type: string
7  numberOfDogs:
8    type: number

1# components/schemas/user/models.yml
2
3{{ pagination({ path: "./singleUserResponse.yml" }) }}

or simply

1{{ pagination("./singleUserResponse.yml") }}

Would output:

1type: object
2required:
3  - meta
4  - data
5properties:
6  meta:
7    $ref: "#/components/schemas/Meta"
8  data:
9    type: array
10    items: 
11      $ref: "./singleUserResponse.yml"

---

To specify another pagination model:

1# components/schemas/user/singleUserResponse.yml
2
3type: object
4properties:
5  name:
6    type: string
7  numberOfDogs:
8    type: number

1# components/schemas/user/models.yml
2
3{{ pagination({ paginationModel: "#/components/schemas/Pagination" }) }}

Would output:

1type: object
2required:
3  - meta
4  - data
5properties:
6  meta:
7    $ref: "#/components/schemas/Pagination"
8  data:
9    type: array
10    items: 
11      $ref: "./model.yml"

---

To alter or remove required fields:

1# components/schemas/user/singleUserResponse.yml
2
3type: object
4properties:
5  name:
6    type: string
7  numberOfDogs:
8    type: number

1# components/schemas/user/models.yml
2
3{{ pagination({ required: ['meta'] }) }}

Would output:

1type: object
2required:
3  - meta
4properties:
5  meta:
6    $ref: "#/components/schemas/Pagination"
7  data:
8    type: array
9    items: 
10      $ref: "./model.yml"

1# components/schemas/user/models.yml
2
3{{ pagination({ required: [] }) }}

Would output:

1type: object
2properties:
3  meta:
4    $ref: "#/components/schemas/Pagination"
5  data:
6    type: array
7    items: 
8      $ref: "./model.yml"