tessl/npm-swagger

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

—

Pending

Overview

Eval results

Files

Editor Integration

Name: tessl/npm-swagger
Author: tessl

Browser-based Swagger editor integration with real-time validation, file synchronization, and built-in development tools for API specification editing.

Capabilities

Swagger Editor

Launches an integrated browser-based Swagger editor with real-time validation and automatic file synchronization.

swagger project edit [directory] [options]

# Options:
# -s, --silent          Do not open browser automatically
# --host <host>         Hostname for editor server (default: 127.0.0.1)
# -p, --port <port>     Port for editor server (default: auto-assigned)

Usage Examples:

# Open editor for current project
swagger project edit

# Open editor on specific host and port
swagger project edit --host 0.0.0.0 --port 8080

# Start editor server without opening browser
swagger project edit --silent

Programmatic Usage:

/**
 * Launch Swagger editor for project
 * @param {string} directory - Project directory
 * @param {Object} options - Editor options
 * @param {boolean} options.silent - Don't open browser
 * @param {string} options.host - Server hostname
 * @param {number} options.port - Server port
 * @param {Function} cb - Callback function
 */
function edit(directory, options, cb);

The editor provides:

Real-time Swagger 2.0 validation
Syntax highlighting for YAML/JSON
Interactive API documentation
Try-it functionality for testing endpoints
Automatic file synchronization with local project

Project Browser Client

Opens the running project in a browser for testing and interaction with the live API.

swagger project open [directory]

Usage Examples:

# Open current project in browser
swagger project open

# Open specific project
swagger project open ./my-api

Programmatic Usage:

/**
 * Open project in browser
 * @param {string} directory - Project directory
 * @param {Object} options - Browser options
 * @param {Function} cb - Callback function
 */
function open(directory, options, cb);

Editor Configuration

Default Configuration

The Swagger editor is configured with the following default settings:

const editorConfig = {
  analytics: { google: { id: null } },
  disableCodeGen: true,
  disableNewUserIntro: true,
  examplesFolder: '/spec-files/',
  exampleFiles: [],
  autocompleteExtension: {},
  useBackendForStorage: true,
  backendEndpoint: '/editor/spec',
  backendHealthCheckTimeout: 5000,
  useYamlBackend: true,
  disableFileMenu: true,
  enableTryIt: true,
  headerBranding: false,
  brandingCssClass: null,
  schemaUrl: '/schema/swagger.json',
  importProxyUrl: 'https://cors-it.herokuapp.com/?url='
};

File Synchronization

The editor automatically synchronizes changes with the local Swagger specification file:

Load Path: /editor/spec - Editor fetches current specification
Save Path: /editor/spec - Editor saves changes via PUT requests
Config Path: /config/defaults.json - Editor configuration endpoint
Default File: api/swagger/swagger.yaml - Local specification file

Server Integration

The editor runs as a Connect middleware server with the following endpoints:

// Server paths
const SWAGGER_EDITOR_SERVE_PATH = '/';              // Editor static files
const SWAGGER_EDITOR_LOAD_PATH = '/editor/spec';    // Specification loading
const SWAGGER_EDITOR_SAVE_PATH = '/editor/spec';    // Specification saving
const SWAGGER_EDITOR_CONFIG_PATH = '/config/defaults.json'; // Configuration

Browser Utilities

Cross-Platform Browser Support

/**
 * Open URL in system browser
 * @param {string} url - URL to open
 * @param {Function} cb - Callback function
 * @param {string} platform - Platform override for testing
 */
function open(url, cb, platform);

Platform Support:

const platformOpeners = {
  darwin: function(url, cb),   // macOS
  win32: function(url, cb),    // Windows
  linux: function(url, cb),    // Linux
  other: function(url, cb)     // Other platforms
};

Usage Examples:

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

// Open Swagger documentation
browser.open('https://swagger.io/docs/', function(err) {
  if (err) console.error('Failed to open browser:', err);
});

// Open local development server
browser.open('http://localhost:10010', function(err) {
  if (err) console.error('Failed to open browser:', err);
});

Network Utilities

Port Availability Checking

/**
 * Check if a network port is open/available
 * @param {number} port - Port number to check
 * @param {number} timeout - Timeout in milliseconds (default: 100)
 * @param {Function} cb - Callback function (err, isOpen)
 */
function isPortOpen(port, timeout, cb);

Usage Examples:

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

// Check if project server is running
netutil.isPortOpen(10010, function(err, isOpen) {
  if (err) {
    console.error('Error checking port:', err);
  } else if (isOpen) {
    console.log('Server is running on port 10010');
  } else {
    console.log('Port 10010 is not in use');
  }
});

// Check with custom timeout
netutil.isPortOpen(8080, 500, function(err, isOpen) {
  console.log('Port 8080 is', isOpen ? 'open' : 'closed');
});

This utility is used internally to verify that the development server is running before attempting to open the project in a browser.

Install with Tessl CLI