Multiple specs

For some applications, it may be desirable to split your openapi definitions into multiple, separate files. to do this, you can specify in conf/app.ts a second openapi configuration under a different name (e.g. admin), like so:

export default (psy: Psyconf) => {
  psy.set('openapi', {
    // ...
  })

  psy.set('openapi', 'admin', {
    // you must include a custom filename for all non-default openapi specs
    outputFilename: 'admin.openapi.json',
    // ...
  })
}

This can also be useful, if, say, you have an api which services both a mobile team, and a web team, and you need each of them to be configured differently. This could be critical for you, since if a response payload contains a string enum, that string enum is treated strictly as a string, and the description will contain all the possible values. This is important, since currently many mobile environments will raise exceptions when encountering unexpected enums (which can happen if your database enums shift over time), forcing you to have to version your backend to serve different enums to different versions of a mobile app, which would be absolutely horrible for you.

The following approach does away with these concerns, since you can suppress response enums with a single config line. This enables you to deliver two identical openapi files, except that one will suppress response enums, while the other will not.

export default (psy: Psyconf) => {
  psy.set('openapi', 'web', {
    outputFilename: 'web.openapi.json',
  })

  psy.set('openapi', 'mobile', {
    outputFilename: 'mobile.openapi.json',
    // if a response payload contains a string enum, that string enum is treated strictly
    // as a string, and the description will contain all the possible values. This is important,
    // since currently many mobile environments will raise exceptions when encountering unexpected
    // enums (which can happen if your database enums shift over time), forcing you to have to version your
    // backend to serve different enums to different versions of a mobile app, which would be absolutely
    // horrible for you.
    suppressResponseEnums: true,
  })
}

When taking this strategy, make sure to update your ApplicationController#openapiNames getter to include both web and mobile, like so:

class ApplicationController extends PsychicController {
  ...

  public static get openapiNames(): PsychicOpenapiNames<ApplicationController> {
    return ['web', 'mobile']
  }
}

This will automatically compile all OpenAPI decorators used in controllers that extend ApplicationController to both mobile.openapi.json and web.openapi.json.