@voilab/koa-scalar

v0.2.4

Published

2 days ago

Koa router based on Openapi@3 and koa-scalar

0High
0Medium
0Low

tafel

alexandre_voilab

openapi3 openapi 3 openapi@3 koa scalar koa router

Koa Scalar

Introduction

This is a router for Koa, which parses a local directory of Openapi@3 files (yaml or json) to automatically generate routes and parameters validation (input and output).

Dependencies

| Dependency | Dependency type | What for? | | --- | --- | --- | | koa | Peer | used as main web framework | | @scalar/openapi-parser | Main | used for Openapi@3 validation, dereferencing, and web client documentation | | fastest-validator | Main | used for parameters validation | | koa-tree-router | Main | used for routing in Koa | | lodash | Secondary | used for simplifing POJO manipulation (through get, set and merge exclusively) | | yaml | Secondary | used to translate *.yaml files to POJO |

Basic usage

// index.js
const Koa = require('koa')
const { Router } = require('voilab/koa-scalar')

const app = new Koa()

const router = new Router({
    docDir: './openapi',
    ctrlDir: './controllers',
    version: '/v1',
    apiExplorer: {
        url: '/docs'
    }
})

// builds routes based on Openapi specification
await router.build()

// add these routes to koa
app.use(router.routes())

app.listen(3000)
console.log('Documentation available on http://localhost:3000/docs')
console.log('API available on http://localhost:3000/v1')

Configurations

| Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | docDir | string | yes || Relative or absolute path to Openapi specification files | | ctrlDir | string | yes || Relative or absolute path to javascript controller files | | version | string | yes || API version name | | parseInput | boolean | no | true | Parse arrays and objects input parameters when they are defined as strings | | validateInput | boolean | no | true | Validate input against Openapi definition before controller is called | | validateOutput | boolean | no | false | Validate Koa body content against Openapi response definition | | apiExplorer | object | no | {} | Api explorer documentation configuration | | apiExplorer.url | string | no | undefined | Path url to documentation | | apiExplorer.rootUrl | string | no | undefined | Root path url used for loading api reference js script in some edge cases | | apiExplorer.envWhitelist | string[] | no | [] | Names of env vars, allowed to be replaced in documentation | | apiExplorer.title | string | no | undefined | Documentation title | | apiExplorer.lang | string | no | undefined | HTML tag language code | | apiExplorer.head | string | no | undefined | Custom <head> for documentation (CSS mainly) | | apiExplorer.nonce | function | no | undefined | Function with Koa context as first argument, which returns the nonce | | apiExplorer.config | object | no | vendor defaults| Custom configuration for Scalar (documentation on Github) | | validatorConfig | object | no | vendor defaults | Custom configuration for (or instance of) FastestValidator (documentation on Github) | | routerConfig | object | no | vendor defaults | Custom configuration for (or instance of) KoaTreeRouter (documentation on Github) |

Controllers folders structure

Consider Openapi documentation files such as this:

openapi
|-- index.yaml
|-- paths
    |-- users
        |-- search.yaml

Where the two files content are:

# ./openapi/index.yaml
openapi: 3.1.1
info:
  title: Koa router test
  description: Koa router
security:
  - bearerAuth: []
servers:
  - url: /v1 # server must contain the version number

# ./openapi/paths/users/search.yaml
/users/search:
  head:
    summary: Count users
    security:
      - bearerAuth: []
  get:
    summary: Search users
    security:
      - bearerAuth: []

And a router config like that:

const router = new Router({
    docDir: './openapi',
    ctrlDir: './controllers',
    version: 'v1'
})

Controllers folder will look like this:

controllers
|-- middleware
|   |-- koaBody.js
|-- security
|   |-- bearerAuth.js
|-- v1
    |-- users
        |-- search.js

The security module exports a function, itself returning a standard koa middleware:

// ./controllers/security/bearerAuth.js
module.exports = (options, schema) => (ctx, next) => {
    console.log('bearer', options, schema, ctx.params)
    return next()
}

The defined route exports each HTTP lowercased method as a standard koa middleware:

// ./controllers/v1/users/search.js
const { countUsers, listUsers } = require('some/user/service.js')

module.exports = {
    async head(ctx) {
        ctx.set('X-Total-Count', await countUsers())
        ctx.status = 204
    },
    async get(ctx) {
        ctx.body = await listUsers()
    }
}

Middlewares

Middlewares modules are defined in the Openapi file like this. You can either just put the name, or an object with name and options (which is itself an object).

/test:
  get:
    x-middleware:
      - name: koaBody
        options:
          limit: 50mb
      - custom

In controller folder structure, middlewares are placed inside middleware subfolder (see controller folder structure above).

The middleware consists of a function returning a standard koa middleware. The config argument is always an object (it cannot be null or undefined).

// ./controllers/middleware/koaBody.js
const koaBody = require('koa-body')

module.exports = config => koaBody({
  includeUnparsed: true,
  ...config
})

// ----------------------------------------------

// ./controllers/middleware/custom.js
module.exports = config => (ctx, next) => {
  console.log('my custom middleware')
  return next()
}

Limitations

Fixed Scalar API reference version

The version shipped with this library is fixed to [email protected].

If you need an other version, you will need to fork this repository and replace the file /src/docs/api-reference.js, and maybe /src/docs/index.html if this is needed by the new javascript version.

You can use the script npm run scalar-update to automatically download the latest Scalar API reference.

Validation limited to Content-Type application/json

Openapi@3 lets you configure different content types for requests and responses bodies (application/json, application/xml and so on). Only application/json is taken into account regarding validation.

Mix of static and dynamic routes

Due to how KoaTreeRouter works, it's not possible to configure static and dynamic routes on the same base path.

The example below WILL NOT WORK.

/users/addresses-types:
  get:
    summary: List addresses types (private, professional, etc.)

/users/{user_id}:
  get:
    summary: Get user
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid

There is an open pull request: https://github.com/steambap/koa-tree-router/pull/29

CSP

If you have CSP enabled, you must accept inline stylesheets, since Scalar imports dynamically (and without nonce) the Tailwind CSS.

For the inline javascript of the HTML index file, you can pass the nonce at config time:

const router = new Router({
    docDir: './openapi',
    ctrlDir: './controllers',
    version: 'v1',
    apiExplorer: {
      nonce: koaCtx => koaCtx.state.myNonce // use any system you want to generate the nonce
    }
})

FAQ

How to disable documentation?

Just leave apiExplorer.url empty. This way, no route will point to documentation.

How can I define a nullable parameter?

In [email protected], the type property can be an array (see the validation specification). You can define Scalar nullable schema property to true, or add null in type array.

Do Openapi files support environment variables?

Yes, this library has a (very) simple environment vars replacement, working with both YAML and JSON files. It uses process.env.* to find the value.

ENV_VAR="test"
ENV_DEFAULT="default value"
ENV_URL="https://www.somesite.net/v1"

info:
  title: "API docs for environment %env(ENV_VAR)%"
  description: "Some description: %env(ENV_DEFAULT:ENV_VAR)%, %env(ENV_DEFAULT:ENV_VAR_EMPTY)%"

servers:
  - url: %env(ENV_URL)%

Results in

info:
  title: "API docs for environment test"
  description: "Some description: test, default value"

servers:
  - url: https://www.somesite.net/v1

You need to whitelist all your env vars if you want the replacement to work

new Router({
  apiExplorer: {
    envWhitelist: ['ENV_VAR', 'ENV_DEFAULT', 'ENV_URL']
  }
})

Advanced validation

This lib uses FastestValidator for validation. You can use Openapi schema parameter format to use any of the validators available.

You must use the shorthand method to add options to the validator.

name: email
schema:
  type: string
  format: email|normalize

name: age
schema:
  type: integer
  format: positive

I don't want to convert value (for arrays, boolean, integer, string, etc)

By default all values are converted into the defined type, because this lib defaults convert option in FastestValidator to true.

If you don't want to convert values, you have to force conversion to false.

name: ids
schema:
  type: array
  format: convert:false
  items:
    type: string

name: age
schema:
  type: integer
  format: positive|convert:false

Contribution

Please send pull requests improving the usage and fixing bugs, improving documentation and providing better examples, or providing some tests, because these things are important.

Run tests with npm run test. It uses jest behind the scene.

License

koa-scalar is available under the MIT license.