Swagger
Split and link large API spec files, used by tools such asJSON or YAML) files and link them.
This package helps to split the larger API spec files in to smaller (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,
You can link http_200 as follows. (using the path "#success/http_200")
Path to the splitted file should be valid and accessible
in your app
refer the below mentioned code
'use strict'const swaggerTools = ;const xrefModule = ;xrefModule;
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