duncanhall / expand-swagger-refs

Automatically expand $ref values in your Swagger schema via function, file or stdin

expand-swagger-refs

Automatically expand $ref values in your Swagger schema:

• From a function
• From a file
• From stdin
• Zero dependencies

Install

npm install expand-swagger-refs

NOTE: If you want to use the file or stdin options, you may want to install globally with -g

Module functions

Importing the module provides 2 methods for expansion, with or without mutation:

const { expand, expanded } = require('expand-swagger-refs');
const schema = require('./api/swagger.json');

// Create a copy of the schema, with $ref values expanded: 
const expandedSchema = expanded(schema);

// Or expand the schema object in-place (mutates the object):
expand(schema)

stdin > stdout

With the module installed globally, the swagger-expand command is available and will accept valid JSON to stdin:

swagger-expand < swagger.json

The expanded result is written to stdout:

swagger-expand < swagger.json > expanded.json

File input

The swagger-expand command also accepts a filepath as an input:

swagger-expand ~/lol/swagger.json

By default the expanded result will be written adjacent to the input file with -expanded added to the basename. Eg, the input above would write the result to ~/lol/swagger-expanded.json. Absolute and relative paths are supported.

You can tell swagger-expand to overwrite the input file with the expanded result using the -o option:

swagger-expand ~/rofl/swagger.json -o

expand-swagger-refs's Issues

Ability to use stdin and stdout

I'd really appreciate to see the ability to use stdin as input source and stdout as output source for the script, as that'd allow transformation of data, without writing it to (temporary) files in between.

Input via stdin doesn't work for large templates

Thanks for implementing stdin and stdout in such a timely manner.

There still seems to be a bug: If you pass a swagger template with more than 65535 characters to swagger-expand via stdin it fails with an error message.
The exact error message varies based on the data provided (as depending on its length it gets corrupted differently), but it's always related to the data not being compliant with JSON anymore.
E.g. with https://api.zalando.com/schema/swagger.json, I get:

foo@bar:~$ swagger-expand /tmp/swagger.json
Expanded file written to /tmp/swagger.json-expanded
foo@bar:~$$ swagger-expand < /tmp/swagger.json 
undefined:1322
                        "description",: "Category Key response.",
                                     ^

SyntaxError: Unexpected token , in JSON at position 65520
    at JSON.parse (<anonymous>)
    at ReadStream.<anonymous> (~/node_modules/expand-swagger-refs/bin/from-stdin.js:14:29)
    at emitNone (events.js:91:20)
    at ReadStream.emit (events.js:188:7)
    at endReadableNT (_stream_readable.js:975:12)
    at _combinedTickCallback (internal/process/next_tick.js:80:11)
    at process._tickCallback (internal/process/next_tick.js:104:9)

NodeJS version used is 7.7.4.