xref

    2.1.0 • Public • Published

    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

    Install

    npm i xref

    DownloadsWeekly Downloads

    2

    Version

    2.1.0

    License

    MIT

    Last publish

    Collaborators

    • rpg