Swagger Node CLI

Swagger Node CLI is a comprehensive command-line interface for designing and building Swagger-compliant APIs entirely in Node.js. It integrates with popular Node.js servers including Express, Hapi, Restify, and Sails, as well as any Connect-based middleware. The tool enables developers to specify, build, and test APIs from the very beginning on their laptop, allowing for iterative design changes without rewriting implementation logic.

Package Information

• Package Name: swagger
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -g swagger

Core Imports

For programmatic usage of internal modules:

// Command modules
const { convert, validate } = require('swagger/lib/commands/commands');
const project = require('swagger/lib/commands/project/project');

// Utility modules
const cli = require('swagger/lib/util/cli');
const spec = require('swagger/lib/util/spec');
const browser = require('swagger/lib/util/browser');

Basic Usage

Primary usage is through CLI commands:

# Create a new Swagger project
swagger project create my-api --framework express

# Start development server
cd my-api
swagger project start

# Edit API specification
swagger project edit

# Validate Swagger document
swagger validate api/swagger/swagger.yaml

# Convert Swagger 1.2 to 2.0
swagger convert old-api.json > new-api.yaml

Architecture

Swagger Node CLI is built around several key components:

• CLI Interface: Two main binaries (swagger and swagger-project) providing complete command-line functionality
• Project Management: Full project lifecycle support from creation to testing and deployment
• Swagger Editor Integration: Embedded browser-based editor with real-time validation
• Multi-Framework Support: Built-in templates and configurations for Express, Hapi, Restify, Sails, and Connect
• Validation System: Comprehensive Swagger specification validation with detailed error reporting
• Development Server: Integrated server with hot reloading, mocking, and debugging capabilities

Capabilities

Project Management

Complete project lifecycle management including creation, configuration, development server, and testing.

# Create new project
swagger project create [name] [--framework <framework>]

# Start development server  
swagger project start [directory] [--debug] [--debug-brk] [--mock] [--open] [--node-args <args>]

# Verify project configuration
swagger project verify [directory] [--json]

# Run project tests
swagger project test [directory_or_file] [--debug] [--debug-brk] [--mock]

# Generate test templates
swagger project generate-test [directory] [--path-name <path>] [--test-module <module>] [--assertion-format <type>] [--force] [--load-test <path>]

Project Management

Swagger Editor Integration

Browser-based Swagger editor with real-time validation and file synchronization.

# Open Swagger editor
swagger project edit [directory] [--silent] [--host <host>] [--port <port>]

# Open project in browser
swagger project open [directory]

Editor Integration

Document Validation and Conversion

Swagger document validation and format conversion utilities.

# Validate Swagger document
swagger validate [swaggerFile] [--json]

# Convert Swagger 1.2 to 2.0
swagger convert <swaggerFile> [apiDeclarations...] [--output-file <fileName>]

# Open Swagger documentation
swagger docs

Validation and Conversion

Programmatic API

Internal modules for programmatic usage in Node.js applications.

// CLI utilities
const cli = require('swagger/lib/util/cli');

// Swagger specification validation  
const spec = require('swagger/lib/util/spec');

// Browser integration
const browser = require('swagger/lib/util/browser');

// Network utilities
const net = require('swagger/lib/util/net');

// Feedback system
const feedback = require('swagger/lib/util/feedback');

// Project management
const project = require('swagger/lib/commands/project/project');

// Command execution
const commands = require('swagger/lib/commands/commands');

Programmatic API

Framework Support

Supported Node.js frameworks and their configurations:

• Connect: Base framework with middleware support
• Express: Express.js framework (overlay on Connect)
• Hapi: Hapi.js framework (overlay on Connect)
• Restify: Restify framework (overlay on Connect)
• Sails: Sails.js framework with custom templates

Test Configuration

Supported test frameworks and assertion libraries:

• Test Modules: supertest, request
• Assertion Types: expect, should, assert
• Dependencies: Automatically managed test dependencies including mocha, chai, z-schema