S-Swagger

A modern, dynamic Swagger/OpenAPI UI renderer and test runner with an intuitive interface for API documentation and testing.

✨ Features

• 🎨 Modern UI: Beautiful, responsive interface with smooth animations
• 🚀 Request Runner: Built-in API testing tool with tabbed interface
• 🔐 Multi-Profile Authentication: Support for Bearer, Basic Auth, and API Key authentication
• 📝 Smart Code Editor: Syntax highlighting, auto-formatting, and validation for JSON/XML/HTML
• 🔄 Two-Way Binding: Automatic synchronization between URL bar and parameters
• 📊 Schema Visualization: Interactive schema viewer with expandable references
• 🎯 Tag-Based Organization: Group endpoints by tags for better navigation
• 💾 Local Storage: Persist authentication profiles and request history
• 🌐 Server Selection: Easy switching between different API servers

📦 Installation

npm install s-swagger

🚀 Quick Start

Basic Usage

import { renderSwaggerUI } from 's-swagger';

// Option 1: Provide OpenAPI spec directly
const html = renderSwaggerUI({
    docs: {
        openapi: '3.0.0',
        info: {
            title: 'My API',
            version: '1.0.0'
        },
        // ... rest of your OpenAPI spec
    }
});

// Option 2: Fetch from URL
const html = renderSwaggerUI({
    url: '/api-docs'
});

Express.js Integration

import express from 'express';
import { renderSwaggerUI } from 's-swagger';
import fs from 'fs';
import path from 'path';

const app = express();

// Serve OpenAPI JSON
app.get('/api-docs', (req, res) => {
    const spec = JSON.parse(fs.readFileSync('./openapi.json', 'utf-8'));
    res.json(spec);
});

// Serve Swagger UI
app.get('/swagger', (req, res) => {
    res.send(renderSwaggerUI({
        url: '/api-docs'
    }));
});

app.listen(3000, () => {
    console.log('Server running on http://localhost:3000');
    console.log('Swagger UI available at http://localhost:3000/swagger');
});

🎯 API Reference

renderSwaggerUI(options)

Generates a complete HTML page with the Swagger UI.

Parameters

• options Object
  • docs Object (optional): OpenAPI specification object
  • url String (optional): URL to fetch OpenAPI specification from

Note: Either docs or url must be provided.

Returns

String - Complete HTML page as a string

🔐 Authentication

S-Swagger supports multiple authentication methods with profile management:

Supported Auth Types

1. Bearer Token

   • Simple token-based authentication
   • Automatically adds Authorization: Bearer <token> header

2. Basic Auth

   • Username and password authentication
   • Automatically encodes credentials to Base64

3. API Key

   • Custom header or query parameter
   • Flexible key/value configuration
   • Support for both header and query parameter locations

Profile Management

• Create multiple authentication profiles
• Switch between profiles easily
• Profiles are persisted in localStorage
• Each request can use a different profile

🎨 Features in Detail

Request Runner

The built-in request runner provides a Postman-like experience:

• Tabbed Interface: Work with multiple requests simultaneously
• Parameter Management:
  • Path variables
  • Query parameters
  • Headers
  • Request body
• Body Types:
  • None
  • form-data
  • x-www-form-urlencoded
  • raw (JSON, XML, HTML, JavaScript, Plain Text)
  • binary (file upload)

Code Editor

Advanced code editor with:

• Syntax Highlighting: For JSON, XML, HTML, and JavaScript
• Auto-Formatting: Format JSON with one click
• Auto-Completion: Smart suggestions for JSON keys and values
• Validation: Real-time JSON validation with error markers
• Smart Typing: Auto-closing brackets, quotes, and tags

Schema Viewer

Interactive schema visualization:

• Expandable/collapsible schema sections
• Automatic $ref resolution
• Toggle between example and schema view
• Clear type and requirement indicators

🛠️ Development

Project Structure

package/
├── src/
│   ├── index.ts          # Main entry point
│   ├── script.js         # Client-side JavaScript
│   └── style.css         # Styling
├── package.json
└── tsconfig.json

📋 Requirements

• Node.js 14.x or higher
• Modern browser with ES6 support

📄 License

ISC

🙏 Acknowledgments

Built with modern web technologies and inspired by Swagger UI and Postman.

Made with ❤️ for developers who love clean APIs