JSDoc Swagger SmartFold

A VS Code extension that automatically detects, folds, validates, and provides rich features for @swagger and @openapi blocks within JSDoc comments in JavaScript and TypeScript files.

Features

🔍 Auto-Detection & Folding

Automatically detects JSDoc comments containing the @swagger or @openapi tag and folds them when you open a file. This keeps your code clean and readable while keeping your API documentation close to the code.

✅ Validation

Validates the content of your Swagger/OpenAPI definitions:

YAML Syntax Check: Ensures valid YAML structure.
OpenAPI Schema Validation: Checks against OpenAPI 3.0/3.1 specification (best effort for fragments).
Error Reporting: Displays errors and warnings directly in VS Code's "Problems" panel.
Configurable Severity: Set validation errors as error, warning, or info.

🏷️ CodeLens

Inline information displayed above each Swagger block:

Endpoint Info: Shows HTTP method and path (e.g., GET /api/users)
Parameters Count: Number of parameters defined
Response Codes: List of response status codes
Quick Actions: Copy as JSON with one click

💡 Hover Preview

Hover over @swagger or @openapi tags to see a formatted preview:

Summary and description
Tags
Parameters count
Response codes
YAML preview (truncated for large blocks)

🔧 Quick Fixes

Automatic code actions for common issues:

Add default responses
Add summary field
Add operationId
Fix invalid types

📊 Status Bar

Shows count of Swagger blocks in current file
Click to fold all blocks

Next Block: Jump to the next Swagger block
Previous Block: Jump to the previous Swagger block
Toggle Fold: Fold/unfold the block at cursor

📤 Export

Export Current File: Combine all Swagger blocks from current file into a single OpenAPI document
Export Project: Scan entire project and export all Swagger blocks
Copy as JSON: Copy current block as JSON to clipboard
Format Options: Export as YAML or JSON

👁️ Swagger UI Preview

Live preview of your API documentation using Swagger UI
Dark theme adapted to VS Code
Opens in a side panel

Supported Languages

Language	File Extensions
JavaScript	`.js`
TypeScript	`.ts`
JavaScript React	`.jsx`
TypeScript React	`.tsx`
Vue	`.vue`
Svelte	`.svelte`

Installation

From VS Code Marketplace

Open VS Code
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Search for "JSDoc Swagger SmartFold"
Click Install

Or run:

code --install-extension maxicuyodev.jsdoc-swagger-smartfold

From Open VSX (VSCodium, Gitpod, etc.)

code --install-extension maxicuyodev.jsdoc-swagger-smartfold

Official Downloads

Visual Studio Marketplace: VS Marketplace
Open VSX: Open VSX

Usage

Open any supported file (.js, .ts, .jsx, .tsx, .vue, .svelte).
Add a JSDoc block with @swagger or @openapi:

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Returns a list of users.
 *     description: Optional description.
 *     tags:
 *       - Users
 *     parameters:
 *       - name: limit
 *         in: query
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: A JSON array of user names
 *         content:
 *           application/json:
 *             schema: 
 *               type: array
 *               items: 
 *                 type: string
 */
app.get('/api/users', (req, res) => { ... });

Or using @openapi:

/**
 * @openapi
 * /api/products/{id}:
 *   get:
 *     summary: Get product by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Product details
 *       404:
 *         description: Product not found
 */
app.get('/api/products/:id', (req, res) => { ... });

The block will automatically fold (if enabled).
CodeLens will show endpoint info above the block.
Hover over @swagger/@openapi to see a preview.
If there are syntax errors, they will appear in the Problems panel with Quick Fix suggestions.

Commands

All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Description	Keyboard Shortcut
`Swagger SmartFold: Fold Swagger Blocks`	Fold all Swagger blocks	`Ctrl+Alt+S F`
`Swagger SmartFold: Unfold Swagger Blocks`	Unfold all Swagger blocks	`Ctrl+Alt+S U`
`Swagger SmartFold: Toggle Fold at Cursor`	Toggle fold for block at cursor	`Ctrl+Alt+S T`
`Swagger SmartFold: Go to Next Swagger Block`	Navigate to next block	`Ctrl+Alt+S ↓`
`Swagger SmartFold: Go to Previous Swagger Block`	Navigate to previous block	`Ctrl+Alt+S ↑`
`Swagger SmartFold: Export Swagger to File`	Export current file's blocks	-
`Swagger SmartFold: Export All Project Swagger to File`	Export all project blocks	-
`Swagger SmartFold: Copy Swagger Block as JSON`	Copy current block as JSON	-
`Swagger SmartFold: Preview Swagger UI`	Open Swagger UI preview	`Ctrl+Alt+S P`

Note: On macOS, use Cmd instead of Ctrl.

Right-click inside a supported file to access:

Toggle Fold at Cursor
Copy Swagger Block as JSON
Preview Swagger UI

Configuration

This extension contributes the following settings:

Setting	Type	Default	Description
`swaggerFold.autoFold`	boolean	`true`	Auto-fold @swagger/@openapi JSDoc blocks when opening a file
`swaggerFold.highlight`	boolean	`true`	Enable/disable syntax highlighting for Swagger blocks
`swaggerFold.exclude`	array	`[]`	Glob patterns for files/folders to exclude (e.g., `["/test/", "/node_modules/"]`)
`swaggerFold.validationSeverity`	string	`"warning"`	Severity level for OpenAPI validation errors (`"error"`, `"warning"`, `"info"`)
`swaggerFold.autoFoldDelay`	number	`300`	Delay in milliseconds before auto-folding blocks (0-5000)
`swaggerFold.exportFormat`	string	`"yaml"`	Default format for exporting OpenAPI documents (`"yaml"`, `"json"`)

Example Settings

{
  "swaggerFold.autoFold": true,
  "swaggerFold.highlight": true,
  "swaggerFold.exclude": [
    "**/test/**",
    "**/node_modules/**",
    "**/*.spec.ts"
  ],
  "swaggerFold.validationSeverity": "warning",
  "swaggerFold.autoFoldDelay": 500,
  "swaggerFold.exportFormat": "yaml"
}

Export Feature

Export Current File

Open a file with Swagger blocks
Run command Swagger SmartFold: Export Swagger to File
Choose save location
File will be created with all blocks merged into a valid OpenAPI document

Export Entire Project

Run command Swagger SmartFold: Export All Project Swagger to File
Extension will scan all supported files in the workspace
Choose save location
All Swagger blocks from the project will be merged into a single OpenAPI document

Output Format

The exported document includes:

OpenAPI 3.0.3 specification
Auto-generated info section
All paths merged from blocks
Components/schemas if defined
Tags collected from all endpoints

💖 Support the Project

JSDoc Swagger SmartFold is free and open-source. The FREE version is fully functional and will always remain so.

If you find this extension useful and want to support its development, you can:

☕ Buy me a Cafecito

If you're from Argentina or just want to send a quick tip, you can invite me a cafecito! It's a simple way to say thanks.

🎁 PRO Version ($1)

What's included in PRO?

Feature	FREE	PRO ($1)
Auto-fold @swagger/@openapi blocks	✅	✅
YAML syntax validation	✅	✅
OpenAPI schema validation	✅	✅
Manual fold/unfold commands	✅	✅
Visual highlighting	✅	✅
CodeLens with endpoint info	✅	✅
Hover preview	✅	✅
Quick Fixes	✅	✅
Navigation commands	✅	✅
Export to file	✅	✅
Swagger UI preview	✅	✅
Status bar indicator	✅	✅
Priority support via email	❌	✅
Early access to new features	❌	✅
Name in supporters list	❌	✅
Good karma & warm fuzzy feeling	❌	✅

Note: The PRO version is primarily a way to support the project. All core features are available in the FREE version.

How to Install PRO Version

Purchase the PRO version from Gumroad
Download the .vsix file from the purchase confirmation page
Install manually in VS Code:

code --install-extension jsdoc-swagger-smartfold-pro-X.Y.Z.vsix

Or in VS Code:

Press Ctrl+Shift+P / Cmd+Shift+P
Type "Extensions: Install from VSIX..."
Select the downloaded .vsix file

Development

Building

Clone the repository.
Run npm install to install dependencies.
Run npm run compile to build the source.

Running

Open the project in VS Code.
Press F5 to launch the extension in a new Extension Development Host window.

Scripts

Script	Description
`npm run compile`	Compile TypeScript to JavaScript
`npm run watch`	Watch for changes and recompile
`npm run lint`	Run ESLint
`npm run package`	Create .vsix package
`npm run publish:vs`	Publish to VS Marketplace
`npm run publish:ovsx`	Publish to Open VSX
`npm run publish:all`	Publish to both marketplaces

Project Structure

src/
├── extension.ts      # Main extension entry point
├── constants.ts      # Constants, commands, and configuration
├── swaggerUtils.ts   # Swagger block detection and validation
├── decorator.ts      # Visual decorations for blocks
├── codeLens.ts       # CodeLens provider
├── hoverProvider.ts  # Hover information provider
├── codeActions.ts    # Quick Fix code actions
├── statusBar.ts      # Status bar indicator
├── exporter.ts       # Export functionality
├── preview.ts        # Swagger UI preview webview
└── utils.ts          # Utility functions

Requirements

VS Code 1.80.0 or higher.

Support & Contact

Found a bug? Have a feature request?

🐛 Report bugs: GitHub Issues
💡 Feature requests: GitHub Issues

Support Policy

FREE users: Community support via GitHub Issues
PRO users: Priority email support within 48 hours

Refund Policy

Due to the digital nature of this product and its symbolic pricing ($1), refunds are generally not provided. However, if you experience technical issues that prevent you from using the PRO version, please contact us and we'll do our best to help.

Changelog

See CHANGELOG.md for a list of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the developer community

Enjoy writing documented APIs!

JSDoc Swagger SmartFold

Maximiliano Méndez

JSDoc Swagger SmartFold

Features

🔍 Auto-Detection & Folding

✅ Validation

🏷️ CodeLens

💡 Hover Preview

🔧 Quick Fixes

📊 Status Bar

🚀 Navigation

📤 Export

👁️ Swagger UI Preview

Supported Languages

Installation

From VS Code Marketplace

From Open VSX (VSCodium, Gitpod, etc.)

Official Downloads

Usage

Commands

Context Menu

Configuration

Example Settings

Export Feature

Export Current File

Export Entire Project

Output Format

💖 Support the Project

☕ Buy me a Cafecito

🎁 PRO Version ($1)

What's included in PRO?

How to Install PRO Version

Development

Building

Running

Scripts

Project Structure

Requirements

Support & Contact

Found a bug? Have a feature request?

Support Policy

Refund Policy

Changelog

License