@codefresh-io/cf-openapi
#### Main goals:
Last updated 7 months ago by itai-codefresh .
Original npm · Tarball · package.json
$ cnpm install @codefresh-io/cf-openapi 
SYNC missed versions from official npm registry.

CF-OPENAPI

Main goals:

  1. openapi.json linting

  2. micro-service startup initialization:

  • expose openapi.json through /api/openapi.json endpoint
  • expose ReDoc for openapi.json through /api endpoint
  • expose openapi.json aggregated from dependency services through /api/admin/openapi.json endpoint
  • expose ReDoc for aggregated openapi.json through /api/admin endpoint
  • fetch dependency services' openapi.json specs on startup
  • push openapi.push event with micro-service openapi.json on startup
  • listen to openapi.push event for dependency services
  • (todo) endpoints generation from openapi.json
  • (todo) sdk generation for dependency services

Usage

Installation

npm i @codefresh-io/cf-openapi

yarn add @codefresh-io/cf-openapi

Linter

Use cf-openapi command line interface for validating openapi.json:

cf-openapi lint - lint using default path ./openapi.json (relative to process.cwd())

cf-openapi lint ./some/path/openapi-custom-name.json - lint using given path

cf-openapi lint -p - lint post-processed openapi.json (see: ./lib/components/Processor.component.js)

Use npm script:

{
  "scripts": {
    "openapi-lint": "cf-openapi lint && cf-openapi lint -p"
  }
}

Micro-service startup

Note: this functionality is already integrated into @codefresh-io/service-base

Flow:

const express = require('express');

const { openapi } = require('@codefresh-io/cf-openapi');
const eventbus = require('@codefresh-io/eventbus')
const config = require('./service.config');

const app = express();

const publishInterface = (serviceName, spec) => {
    return eventbus.publishEvent('openapi.push', {
        aggregateId: serviceName,
        props: {
            spec: JSON.stringify(spec)
        }
    }, true, true);
};

const subscribeInterface = (handler) => {
    eventbus.subscribe('openapi.push', (data) => {
        const serviceName = data.aggregateId;
        const spec = JSON.parse(data.props.spec);
        return Promise.resolve()
            .then(() => handler(serviceName, spec));
    });
};

openapi.init(config)
openapi.endpoints().addDependenciesSpecMiddleware(dependenciesMiddleware)
openapi.endpoints().register(app)
openapi.dependencies().fetch();
openapi.events().setPublishInterface(publishInterface)
openapi.events().setSubscribeInterface(subscribeInterface)

app.listen(8080);

openapi.events().subscribe();
openapi.events().publish();

Using multiple instances

Openapi is a "module-singleton" where all components are singletons. This covers most cases except services which consist of multiple app instances (for example cf-api).

For this exception use next code:

const { openapi: first } = require('@codefresh-io/cf-openapi').getInstance('first');
const { openapi: second } = require('@codefresh-io/cf-openapi').getInstance('second');

first.init(serviceConfig_1)
second.init(serviceConfig_2)

Config

Config:

{
    name: PIPELINE_MANAGER, // service name (required)
    root: APP_ROOT, // root path from which openapi.json lookup will be performed
    openapi: {
        spec: {
            specPath: '/api/openapi.json', // default
            redocPath: '/api', // default
            filename: './openapi.json' // default
        },
        dependenciesSpec: {
            specPath: '/api/admin/openapi.json' // default
            redocPath: '/api/admin' // default
        }
    } 
}

Use false value to explicitly disable spec or dependenciesSpec:

{
    openapi: {
        spec: false,
    }
}
Note: since all openapi properties are default the whole openapi property can be omitted

Dependency services are described inside the openapi.json using x-internal-services field:

{
  "openapi": "3.0.0",
  "info": {...},
  "x-internal-services": [
    "pipeline-manager"
  ]
}

Service names are validated through @codefresh-io/internal-service-config. See the readme for available service names.

Current Tags

  • 0.6.1                                ...           latest (7 months ago)

17 Versions

  • 0.6.1                                ...           7 months ago
  • 0.6.0                                ...           9 months ago
  • 0.5.2                                ...           9 months ago
  • 0.5.1                                ...           9 months ago
  • 0.5.0                                ...           9 months ago
  • 0.4.0                                ...           9 months ago
  • 0.4.0-test                                ...           9 months ago
  • 0.3.0                                ...           10 months ago
  • 0.2.4                                ...           a year ago
  • 0.2.3                                ...           a year ago
  • 0.2.2                                ...           a year ago
  • 0.2.1                                ...           a year ago
  • 0.2.0                                ...           a year ago
  • 0.0.5                                ...           a year ago
  • 0.0.4                                ...           a year ago
  • 0.0.3                                ...           a year ago
  • 0.0.2                                ...           a year ago

Copyright 2014 - 2016 © taobao.org |