definma-api/src/api.ts

import swagger from 'swagger-ui-express';
import jsonRefParser, {JSONSchema} from '@apidevtools/json-schema-ref-parser';
import oasParser from '@apidevtools/swagger-parser';


// modifies the normal swagger-ui-express package
// usage: app.use('/api-doc', api.serve(), api.setup());
// the paths property can be split using allOf
// further route documentation can be included in the x-doc property

export default class api {
  static serve () {
    return swagger.serve;
  }

  static setup () {
    let apiDoc: JSONSchema = {};
    jsonRefParser.bundle('api/api.yaml', (err, doc) => {  // parse yaml
      if (err) throw err;
      apiDoc = doc;
      apiDoc.servers.splice(process.env.NODE_ENV === 'production', 1);
      apiDoc.paths = apiDoc.paths.allOf.reduce((s, e) => Object.assign(s, e));  // bundle routes
      apiDoc = this.resolveXDoc(apiDoc);
      oasParser.validate(apiDoc, (err, api) => {  // validate oas schema
        if (err) {
          console.error(err);
        }
        else {
          console.info(process.env.NODE_ENV === 'test' ? '' : 'API ok, version ' + api.info.version);
          swagger.setup(apiDoc);
        }
      });
    });
    return swagger.setup(apiDoc, {customCssUrl: '/static/styles/swagger.css'})
  }

  private static resolveXDoc (doc) {  // resolve x-doc properties recursively
    Object.keys(doc).forEach(key => {
      if (doc[key] !== null && doc[key].hasOwnProperty('x-doc')) {  // add x-doc to description, is styled via css
        doc[key].description += '<details class="docs"><summary>docs</summary>' + doc[key]['x-doc'] + '</details>';
      }
      else if (typeof doc[key] === 'object' && doc[key] !== null) {  // go deeper into recursion
        doc[key] = this.resolveXDoc(doc[key]);
      }
    });
    return doc;
  }
}