koas-core

Koas-core

Koa + OpenAPI Specification = Koas

Koas aims to make it easy to write a RESTful API based on Koa and an Open API V3 Specification.

This is the core package. For more details, see the mono repository README

Installation

npm install koa koas-core

Usage

const Koa = require('koa');
const { koas } = require('koas-core');

const document = {
  openapi: '3.0.2',
  info: {
    title: 'My API',
    version: '1.0.0',
  },
  paths: {
    '/': {
      get: {
        responses: {},
      },
    },
  },
};

const app = new Koa();
app.use(
  koas(document, [
    // Koas plugins go here.
  ]),
);
app.listen(3333);

Plugins

Plugins are functions that take parameters provided by Koas, and return a Koa middleware. Typically, plugins are returned by a function, so options can be passed in.

Example plugin:

function myPlugin(options) {
  return (document, resolveRef, runAlways, validate) => async (ctx, next) => {
    await next();
  };
}

module.exports = {
  myPlugin,
};

TypeScript typings are provided. So it is also possible to write plugins using TypeScript. Pretty much the only type annotation needed is Plugin as the return option for the function.

import { Plugin } from 'koas-core';

export interface MyPluginOptions {
  myOption: unknown;
}

export function myPlugin(options: MyPluginOptions): Plugin {
  return (document, resolveRef, runAlways, validate) => async (ctx, next) => {
    await next();
  };
}