tessl/npm-swagger

Command-line interface for designing and building Swagger-compliant APIs in Node.js

—

Pending

Overview

Eval results

Files

Validation and Conversion

Name: tessl/npm-swagger
Author: tessl

Swagger document validation and format conversion utilities for ensuring specification compliance and migrating between Swagger versions.

Capabilities

Document Validation

Validates Swagger documents against the Swagger 2.0 specification with detailed error and warning reporting.

swagger validate [swaggerFile] [options]

# Options:
# -j, --json  Output validation results as JSON

Usage Examples:

# Validate specific file
swagger validate api/swagger/swagger.yaml

# Validate with JSON output
swagger validate api/swagger/swagger.yaml --json

# Validate from stdin (pipe support)
cat swagger.yaml | swagger validate

# Validate JSON format
swagger validate api-spec.json

Programmatic Usage:

/**
 * Validate Swagger document
 * @param {string} file - Path to Swagger file (null for stdin)
 * @param {Object} options - Validation options
 * @param {boolean} options.json - Output as JSON
 * @param {Function} cb - Callback function
 */
function validate(file, options, cb);

Validation with Spec Utility:

/**
 * Validate Swagger specification object
 * @param {Object} swagger - Swagger specification object
 * @param {Object} options - Validation options
 * @param {boolean} options.json - Output results as JSON
 * @param {Function} cb - Callback function (err, results)
 */
function validateSwagger(swagger, options, cb);

Usage Examples:

const { validate } = require('swagger/lib/commands/commands');
const spec = require('swagger/lib/util/spec');

// Validate file
validate('api/swagger/swagger.yaml', { json: false }, function(err, result) {
  if (err) {
    console.error('Validation failed:', err);
  } else {
    console.log('Validation result:', result);
  }
});

// Validate specification object
const swaggerSpec = {
  swagger: '2.0',
  info: { title: 'My API', version: '1.0.0' },
  paths: {}
};

spec.validateSwagger(swaggerSpec, { json: false }, function(err, result) {
  if (err) {
    console.error('Validation error:', err);
  } else {
    console.log(result); // "Results: 0 errors, 0 warnings"
  }
});

Format Conversion

Converts Swagger 1.2 documents to Swagger 2.0 format with support for multiple API declaration files.

swagger convert <swaggerFile> [apiDeclarations...] [options]

# Options:
# -o, --output-file <fileName>  Write output to specified file

Usage Examples:

# Convert single file to stdout
swagger convert resource-list.json

# Convert with API declarations
swagger convert resource-list.json pet-api.json store-api.json

# Convert and save to file
swagger convert resource-list.json --output-file swagger-2.0.yaml

# Convert multiple declarations to file
swagger convert resource-list.json pet.json store.json user.json --output-file api-v2.yaml

Programmatic Usage:

/**
 * Convert Swagger 1.2 to Swagger 2.0
 * @param {string} filePath - Path to main Swagger 1.2 resource listing
 * @param {string[]} apiDeclarations - Array of API declaration file paths
 * @param {Object} options - Conversion options
 * @param {string} options.outputFile - Output file path
 * @param {Function} cb - Callback function
 */
function convert(filePath, apiDeclarations, options, cb);

Usage Examples:

const { convert } = require('swagger/lib/commands/commands');

// Convert to callback
convert(
  'resource-list.json',
  ['pet-api.json', 'store-api.json'],
  {},
  function(err, result) {
    if (err) {
      console.error('Conversion failed:', err);
    } else {
      console.log('Converted YAML:', result);
    }
  }
);

// Convert and save to file
convert(
  'resource-list.json',
  ['pet-api.json'],
  { outputFile: 'swagger-v2.yaml' },
  function(err) {
    if (err) {
      console.error('Conversion failed:', err);
    } else {
      console.log('Conversion saved to swagger-v2.yaml');
    }
  }
);

Documentation Access

Opens Swagger specification documentation in the system browser.

swagger docs

This command opens the official Swagger 2.0 specification documentation at: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

Input Format Support

File Format Detection

The validation and conversion utilities automatically detect and parse multiple input formats:

/**
 * Parse input data as JSON or YAML
 * @param {string} data - Input data string
 * @returns {Object} Parsed object
 */
function parse(data);

/**
 * Check if data is JSON format
 * @param {string} data - Input data string
 * @returns {boolean} True if JSON format
 */
function isJSON(data);

Supported Formats:

JSON: Standard JSON format with .json extension
YAML: YAML format with .yaml or .yml extension
Stdin: Pipe input from other commands

Error Handling

Both validation and conversion provide detailed error reporting:

Validation Errors:

Specification compliance errors
Schema validation failures
Path and operation validation issues
Parameter and response validation problems

Conversion Errors:

File not found errors
Invalid Swagger 1.2 format
Missing API declaration files
Parsing errors for malformed JSON/YAML

Error Output Format:

Project Errors
--------------
#/paths/users/get: Missing required property 'responses'
#/definitions/User/properties/id: Invalid type 'integer', expected 'number'

Project Warnings
----------------
#/paths/users/get: Unused parameter 'filter'
#/definitions/User: Definition is not referenced by any operation

Results: 2 errors, 1 warnings