OpenAPI / Swagger spec generator for Tyranid

This project provides a way to generate a complete + valid openAPI spec by adding schema annotations to your tyranid models.

NOTE: this library only creates the spec itself, implementation is left to the app code for now (but might be a good feature for this library later on).

Contents

• Schema Options
• Generating the spec
• Exposing a single collection
• "Parent" collections
• Renaming and Restricting certain properties
• Partitioning a collection into multiple "virtual" collections

Schema Options

There are various options for configuring how the tyranid models appear to the public api. You can see the CollectionSchemaOptions (specified in as an object on the schema definition named openAPI) and FieldSchemaOptions (specified on specific fields in the schema as a property named openAPI) interfaces in ./src/interfaces.ts.

Generating the Spec

Once you have specified some collections to be exposed by annotating the schemas, you can generate the actual spec file as follows...

import { Tyr } from 'tyranid';
import { spec } from 'tyranid-openapi';
import { writeFileSync } from 'fs';
import { join } from 'path';

// async function for bootstrap
(async () => {
  // bootstrapping without db to just get schema graph
  await Tyr.config({
    validate: [{ glob: join(__dirname, './models/*.js') }]
  });

  // generate yaml openAPI spec string
  const specString = spec(Tyr, { yaml: true });

  // write out to file
  writeFileSync(join(__dirname, './my-api.yaml'), specString);
})().catch(console.error);

Exposing a single collection

The most basic way to expose a collection to the public api is by setting the openAPI flag to true, and marking a few properties to show. For example...

import { Tyr } from 'tyranid';

export default new Tyr.Collection({
  id: 't01',
  name: 'metric',
  dbName: 'metrics',

  // this indicates that we want GET/PUT/POST/DELETE endpoints
  // for `/metrics` and  `/metrics/{_id}`. Additionally, `read:metrics` and
  // `write:metrics` scopes will be created.
  openAPI: true,

  fields: {
    _id: { is: 'mongoid' },
    organizationId: { is: 'mongoid' },

    // here we mark that we want to expose this field to the api
    // also, since it is marked `required`, api users will recieve
    // an error if they do not POST/PUT data that includes it.
    name: { is: 'string', openAPI: true, required: true }
  }
});

"Parent" collections

Some times there might be several collections which you want to have fall under a single set of permission scopes. Additionally, you want the api url to be nested.

For example, say we have a metrics collection containing metadata about individual metrics (like usage analytics or budget numbers) as well as a metricObservations collection which contains the actual time series. To keep metricObservations in the same permission scope as metrics, we would add the following annotation...

export default new Tyr.Collection({
  id: 'mtg',
  name: 'metricTarget',
  dbName: 'metricTargets',
  openAPI: {
    // define the parent collection, this means that
    // the api paths will be nested under metrics, so
    // `/metrics/{_id}/observations`, `/metrics/{_id}/observations/{_id}`
    parent: 'metric',
    // here we say that we want to use the permission scopes
    // (`read:metrics`/`write:metrics`) for this collection
    useParentScope: true
  },
  fields: {
    _id: { is: 'mongoid' },
    metricId: { link: 'metric', openAPI: true },
    date: { is: 'date', openAPI: true },
    value: { is: 'double', openAPI: true },
    organizationId: { is: 'mongoid' },
    excludeProperty: { is: 'string' },
    type: {
      link: 'metricTargetType',
      openAPI: true
    }
  }
});

Renaming and Restricting certain properties

If there are certain properties that are automatically generated by the database (like timestamps), you can mark them to only be returned / accepted from read endpoints. Additionally, you can provide different public names for properties...

import { Tyr } from 'tyranid';

export default new Tyr.Collection({
  id: 't01',
  name: 'metric',
  dbName: 'metrics',
  openAPI: true,
  fields: {
    _id: { is: 'mongoid' },
    organizationId: { is: 'mongoid' },
    name: { is: 'string', openAPI: true, required: true },
    privateNamedProperty: {
      is: 'string',
      openAPI: {
        // only allow this property in results of GET / PUT / POST,
        // do not allow it to be sent as part of an update (PUT/POST)
        include: 'read',
        // in the spec, this property will be called `publicName`
        name: 'publicName'
      }
    }
  }
});

Partitioning a collection into multiple "virtual" collections

If there is a single database collection which represents several distinct types of data which you wish to expose in different endpoints, you can "partition" the collection...

import { Tyr } from 'tyranid';

export default new Tyr.Collection({
  id: 'i01',
  name: 'item',
  dbName: 'items',
  openAPI: {
    // this will create two new types for the api:  `Plan` + `Task` + `Project`,
    // with `/task`, `/project`, and `/plan` endpoints, etc...
    partition: [
      {
        name: 'plan',
        // here we define a mongodb query to separate the
        // data into their specific partitions
        partialFilterExpression: {
          kind: 'plan'
        }
      },
      {
        name: 'task',
        partialFilterExpression: {
          kind: 'task'
        }
      },
      {
        name: 'project',
        partialFilterExpression: {
          kind: 'project'
        }
      }
    ]
  },
  fields: {
    _id: { is: 'mongoid' },
    organizationId: { is: 'mongoid' },
    name: { is: 'string', openAPI: true, required: true },
    kind: { is: 'string' },
    planField: {
      is: 'string',
      openAPI: {
        // we might want some fields to only appear on
        // certain partitions (can also be an array of partitions)
        partition: 'plan'
      }
    },
    taskField: {
      is: 'string',
      openAPI: {
        partition: 'task'
      }
    },
    nestedPartitionField: {
      is: 'object',
      fields: {
        innerPlanOrProjectField: {
          is: 'string',
          openAPI: {
            partition: ['plan', 'project'],
            name: 'renamedPartitionField'
          }
        },
        innerTaskField: { is: 'string', openAPI: { partition: 'task' } }
      }
    }
  }
});