Split and link large API spec files, used by tools such as Swagger

This package helps to split the larger API spec files in to smaller (JSON or YAML) files and link them.

Basic advantages:

• Feasible to maintain large spec or schema files
• Reuse same API spec definitions between different projects

How to use

in API spec

Look at the below definition section from a regular Swagger API spec file.

definitions:
  Product:
    properties:
      product_id:
        type: string
        description: Unique identifier.
      description:
        type: string
        description: Description of product.
  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string

Above file can be split as follows.

• product.yml

Product:
  properties:
    product_id:
      type: string
      description: Unique identifier.
    description:
      type: string
      description: Description of product.

• error.yml

Error:
  properties:
    code:
      type: integer
      format: int32
    message:
      type: string
    fields:
      type: string

This how to link them in to main file.

definitions:
   Product:
    $href: "#xref#./product.yml"
   Error:
    $href: "#xref#./error.yml"

The xref tag indicates the link to the external files.

You can add more add more properties which are not mentioned in the splitted as follows.

 Error:
   $href: "#xref#./error.yml"
   properties:
    module_id:
      type: string
      description: Unique identifier.
    module_name:
      type: string

Deep paths to inner object

You can specify a path to a object. eg: consider following definition,

{
  "success" : {
    "http_200": {
      "description": "An array of price estimates by product",
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/PriceEstimate"
        }
      }
    },
    "http_400": {
        "description": "An array of price estimates by product",
        "schema": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PriceEstimate"
          }
        }
      }
    
  }
}

You can link http_200 as follows. (using the path "#success/http_200")

{
  "http_responses": {
    "200": {
      "$ref": "#xref#./test/fixtures/json/split/definitions/response.json#success/http_200"
    },
    "default": {
      "description": "Unexpected error",
      "schema": {
        "$ref": "#/definitions/Error"
      }
    }
  }
}

Path to the splitted file should be valid and accessible

in your app

refer the below mentioned code

'use strict'
const swaggerTools = require('swagger-tools');
const xrefModule = require('xref');
xrefModule.xref('./test/fixtures/yaml/split/uber.yaml', (err, spec) => {
	if (err) {
    	return err;
    }
    swaggerTools.initializeMiddleware(spec, (middleware) => {
    /*
    continue your magic
    */
    })
});

CLI tools

xref_cli

This tool is designed to view the entire file after merge. It is bit unfeasible to debug, when file is split in to multiple files. This tool will help you to view the entire spec as one file.

usage:

./node_modules/.bin/xref_cli -s <path to your main spec file> -o <output format. default is YAML>

eg:

• To generate YAML output:

./node_modules/.bin/xref_cli -s test/fixtures/yaml/split/uber.yaml

./node_modules/.bin/xref_cli -s test/fixtures/yaml/split/uber.yaml -o yaml

• To generate JSON output:

./node_modules/.bin/xref_cli -s test/fixtures/yaml/split/uber.yaml -o json

• To save the ouput to a file:

./node_modules/.bin/xref_cli -s test/fixtures/yaml/split/uber.yaml > spec.yaml

xref_swagger_validator

This tool is designed to run the validation through Swagger Tools as mentioned below

swagger-tools validate spec/api.yml

usage:

./node_modules/.bin/xref_swagger_validator -s <path to your main spec file>

eg:

./node_modules/.bin/xref_swagger_validator -s test/fixtures/yaml/split/uber.yaml