OpenAPI 3 to PDF

Export OpenAPI/Swagger specifications to professional PDF documentation with navigable table of contents.

Features

• OpenAPI 3.1+ Support: Full support for OpenAPI 3.1, 3.0, and Swagger 2.0
• Professional Format: Clean, well-structured PDF with table of contents
• Navigable TOC: Clickable links to quickly jump to sections
• Custom Branding: Add your logo and customize cover colors
• Multi-language Support: Generate documentation in English or Spanish
• Complete Documentation: Includes endpoints, schemas, authentication, webhooks, and more
• Customizable Output: Control what gets included and how it's styled
• CLI & Library: Use as a command-line tool or integrate into your Node.js application
• Web Interface: Browser-based UI for easy PDF generation
• Performance Optimized: Handles large APIs with configurable detail levels

Installation

As a global CLI tool

npm install -g openapi3topdf

As a project dependency

npm install openapi3topdf

Quick Start

CLI Usage

# Basic usage
openapi3topdf -i openapi.yaml -o documentation.pdf

# With custom title
openapi3topdf -i api.json -o docs.pdf -t "My API Documentation"

# Exclude examples and deprecated endpoints
openapi3topdf -i spec.yaml -o output.pdf --no-examples --exclude-deprecated

# Summary mode for large APIs
openapi3topdf -i large-api.yaml -o summary.pdf --detail-level summary

# Start web interface
openapi3topdf serve

Library Usage

import { generatePDF } from 'openapi3topdf';

// Basic usage
await generatePDF({
  input: 'path/to/openapi.yaml',
  output: 'documentation.pdf'
});

// Advanced usage with options
await generatePDF({
  input: 'openapi.json',
  output: 'api-docs.pdf',
  options: {
    title: 'My API Documentation',
    includeExamples: true,
    includeSchemas: true,
    includeWebhooks: true,
    detailLevel: 'full', // 'summary' | 'standard' | 'full'
    excludeDeprecated: false,
    filterTags: ['users', 'products'], // Only include specific tags
    colorScheme: 'default' // 'default' | 'minimal' | 'dark'
  }
});

PDF Structure

The generated PDF includes the following sections:

1. Cover Page - Title, version, description, and generation date
2. Table of Contents - Navigable links to all sections
3. Overview - API information, contact, license, and terms
4. Servers - Available servers and their configurations
5. Authentication - Security schemes and requirements
6. Endpoints - Grouped by tags with full details:
   • HTTP method and path
   • Description and summary
   • Parameters (query, path, header, body)
   • Request body with examples
   • Responses with status codes
   • Security requirements
7. Webhooks - Incoming HTTP requests (OpenAPI 3.1+)
8. Schemas - Data models and object definitions

CLI Options

Options:
  -V, --version                    output the version number
  -i, --input <path>               Path to OpenAPI specification file (YAML or JSON) (required)
  -o, --output <path>              Output PDF file path (required)
  -t, --title <title>              Custom title for the documentation
  --language <lang>                Language for PDF content: en or es (default: "en")
  --no-examples                    Exclude examples from the documentation
  --no-schemas                     Exclude schemas section
  --no-webhooks                    Exclude webhooks section
  --exclude-deprecated             Exclude deprecated endpoints
  --detail-level <level>           Detail level: summary, standard, or full (default: "full")
  --filter-tags <tags>             Comma-separated list of tags to include
  --color-scheme <scheme>          Color scheme: default, minimal, or dark (default: "default")
  --cover-bg-color <r,g,b>         Cover background color as RGB (e.g., "41,128,185")
  --cover-text-color <r,g,b>       Cover text color as RGB (e.g., "255,255,255")
  --cover-logo <path>              Path to logo image for cover page (PNG or JPG)
  -h, --help                       display help for command

API Reference

generatePDF(config)

Generate PDF documentation from an OpenAPI specification.

Parameters:

• config (Object)
  • input (String, required) - Path to OpenAPI spec file
  • output (String, required) - Output PDF file path
  • options (Object, optional) - Generation options

Options:

{
  // Basic
  title: String,                    // Custom document title
  language: String,                 // 'en' | 'es' (default: 'en')

  // Cover Customization
  coverBackgroundColor: [r, g, b],  // Cover background RGB color (default: white)
  coverTextColor: [r, g, b],        // Cover text RGB color (default: dark grey)
  coverLogo: String,                // Path to logo image (PNG or JPG)

  // Content
  includeExamples: Boolean,         // Include request/response examples (default: true)
  includeSchemas: Boolean,          // Include schemas section (default: true)
  includeWebhooks: Boolean,         // Include webhooks section (default: true)
  maxExampleLength: Number,         // Max length for examples before truncation (default: 1000)

  // Performance
  detailLevel: String,              // 'summary' | 'standard' | 'full' (default: 'full')

  // Styling
  colorScheme: String,              // 'default' | 'minimal' | 'dark' (default: 'default')
  fontSize: {
    body: Number,                   // Body font size (default: 10)
    heading: Number                 // Heading font size (default: 16)
  },

  // Filtering
  filterTags: Array<String>,        // Only include specific tags
  excludeDeprecated: Boolean        // Exclude deprecated endpoints (default: false)
}

Returns: Promise<void>

Throws: DocuAPIError

generatePDFBuffer(config)

Generate PDF as a buffer without saving to file.

Parameters:

• config (Object) - Same as generatePDF but without output

Returns: Promise<Buffer> - PDF buffer

DocuAPIError

Custom error class for all DocuAPI errors.

Properties:

• message (String) - Error message
• code (String) - Error code: PARSE_ERROR, GENERATION_ERROR, FILE_ERROR, MEMORY_ERROR, VALIDATION_ERROR
• details (Object) - Additional error details

Performance Guidelines

API Size Recommendations

| Endpoints | Schemas | Recommendation | Detail Level | |-----------|---------|----------------|--------------| | 1-50 | <50 | Optimal | full | | 51-200 | 50-150 | Good | full or standard | | 201-500 | 150-200 | Use with caution | standard or summary | | 500+ | 200+ | May fail | summary only |

Performance Tips

1. Use appropriate detail level:

   • summary: Minimal details, fastest generation
   • standard: Balanced details and performance
   • full: All details, slowest for large APIs

2. Exclude unnecessary sections:

   openapi3topdf -i api.yaml -o output.pdf --no-examples --no-webhooks

3. Filter by tags:

   openapi3topdf -i api.yaml -o output.pdf --filter-tags "users,products"

4. Exclude deprecated endpoints:

   openapi3topdf -i api.yaml -o output.pdf --exclude-deprecated

Supported OpenAPI Versions

• OpenAPI 3.1.x (including webhooks)
• OpenAPI 3.0.x
• Swagger 2.0

Supported Features

OpenAPI 3.x Features

• ✅ Paths and operations
• ✅ Parameters (query, path, header, cookie)
• ✅ Request bodies with multiple content types
• ✅ Responses with status codes
• ✅ Schemas and components
• ✅ Security schemes (API Key, HTTP, OAuth2, OpenID Connect)
• ✅ Servers with variables
• ✅ Tags and grouping
• ✅ Webhooks (OpenAPI 3.1+)
• ✅ Examples
• ✅ Deprecated endpoints
• ✅ Circular references
• ✅ Discriminator (polymorphism)
• ✅ oneOf, anyOf, allOf

PDF Features

• ✅ Table of contents with internal links
• ✅ Automatic pagination
• ✅ Color-coded HTTP methods
• ✅ Status code color coding
• ✅ Professional tables (AutoTable)
• ✅ Code syntax formatting
• ✅ Deprecated badges
• ✅ Page numbering
• ✅ Custom cover with logo and colors

Troubleshooting

Common Errors

Error: File not found

Make sure the input file path is correct and the file exists.

Error: Invalid OpenAPI specification

Validate your OpenAPI spec using an online validator like:
- https://editor.swagger.io/
- https://apitools.dev/swagger-parser/online/

Error: Too many endpoints

Your API exceeds the maximum limit (500 endpoints).
Solutions:
1. Use --filter-tags to include only specific sections
2. Split your API into multiple specs
3. Use --detail-level summary to reduce memory usage

Error: YAML parse error

Check your YAML syntax. Common issues:
- Incorrect indentation
- Missing colons
- Invalid characters

Memory Issues

If you encounter memory errors with large APIs:

1. Reduce detail level: --detail-level summary
2. Exclude examples: --no-examples
3. Filter tags: --filter-tags "essential,core"
4. Increase Node.js memory: NODE_OPTIONS="--max-old-space-size=4096" openapi3topdf ...

Examples

Example 1: Complete Documentation

openapi3topdf -i examples/sample-api.yaml -o complete-docs.pdf

Example 2: Developer-Friendly (No Internal Schemas)

openapi3topdf -i api.yaml -o dev-docs.pdf --no-schemas

Example 3: Public API (No Deprecated)

openapi3topdf -i api.yaml -o public-docs.pdf --exclude-deprecated

Example 4: Quick Reference (Summary Mode)

openapi3topdf -i api.yaml -o quick-ref.pdf --detail-level summary --no-examples

Example 5: Custom Branded Cover

# With custom colors
openapi3topdf -i api.yaml -o branded.pdf \
  --cover-bg-color "41,128,185" \
  --cover-text-color "255,255,255"

# With logo and custom colors
openapi3topdf -i api.yaml -o branded-logo.pdf \
  --cover-logo "./company-logo.png" \
  --cover-bg-color "33,33,33" \
  --cover-text-color "236,240,241"

# Just logo with default colors
openapi3topdf -i api.yaml -o logo-docs.pdf --cover-logo "./logo.png"

Example 5b: Spanish Documentation

# Generate documentation in Spanish
openapi3topdf -i api.yaml -o documentacion.pdf --language es

# Spanish with custom branding
openapi3topdf -i api.yaml -o documentacion-marca.pdf \
  --language es \
  --cover-logo "./logo.png" \
  --cover-bg-color "51,51,245" \
  --cover-text-color "255,255,255"

Example 6: Programmatic Usage

import { generatePDF, DocuAPIError, ERROR_CODES } from 'openapi3topdf';

try {
  await generatePDF({
    input: 'api.yaml',
    output: 'documentation.pdf',
    options: {
      title: 'My API v2.0',
      detailLevel: 'full',
      includeExamples: true,
      colorScheme: 'default'
    }
  });

  console.log('PDF generated successfully!');
} catch (error) {
  if (error instanceof DocuAPIError) {
    console.error(`DocuAPI Error [${error.code}]: ${error.message}`);

    if (error.code === ERROR_CODES.MEMORY_ERROR) {
      console.log('Tip: Try using --detail-level summary');
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Example 7: Custom Cover with Logo

import { generatePDF } from 'openapi3topdf';

// Branded PDF with custom cover
await generatePDF({
  input: 'api.yaml',
  output: 'branded-api-docs.pdf',
  options: {
    title: 'My Corporate API',
    coverLogo: './company-logo.png',
    coverBackgroundColor: [41, 128, 185],  // Blue background
    coverTextColor: [255, 255, 255],       // White text
    includeExamples: true,
    detailLevel: 'full'
  }
});

// Dark theme cover
await generatePDF({
  input: 'api.yaml',
  output: 'dark-theme-docs.pdf',
  options: {
    title: 'Dark Theme API Documentation',
    coverBackgroundColor: [33, 33, 33],    // Dark grey
    coverTextColor: [236, 240, 241],       // Light grey
    includeExamples: true
  }
});

Development

Project Structure

openapi3topdf/
├── bin/
│   └── cli.js              # CLI entry point
├── src/
│   ├── index.js            # Main API
│   ├── parser.js           # OpenAPI parser
│   ├── pdf-generator.js    # PDF orchestrator
│   ├── constants/
│   │   └── config.js       # Configuration constants
│   ├── utils/
│   │   ├── pagination.js   # Auto-pagination helpers
│   │   ├── link-manager.js # Internal PDF links
│   │   ├── styles.js       # Styling functions
│   │   └── formatters.js   # Text formatters
│   └── sections/
│       ├── cover.js        # Cover page
│       ├── toc.js          # Table of contents
│       ├── info.js         # API information
│       ├── servers.js      # Servers section
│       ├── auth.js         # Authentication
│       ├── endpoints.js    # Endpoints (main section)
│       ├── schemas.js      # Data models
│       └── webhooks.js     # Webhooks (3.1+)
└── examples/
    └── sample-api.yaml     # Sample API spec

Running Tests

npm test

Building from Source

git clone https://bitbucket.org/edualfio/openapi3topdf.git
cd openapi3topdf
npm install
npm link

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or feature requests, please open an issue on Bitbucket.

Roadmap

• [x] Custom logo support ✅
• [x] Custom cover colors ✅
• [x] Multi-language support (English/Spanish) ✅
• [ ] Multiple color themes
• [ ] HTML output format
• [ ] Markdown output format
• [ ] Custom templates
• [ ] Interactive PDF with forms
• [ ] Comparison mode (diff between versions)

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Edu Alfaro - https://edualfaro.com

Project Link: https://bitbucket.org/edualfio/openapi3topdf