JSDoc OpenAPI YAML Highlighting

A Visual Studio Code extension that provides YAML syntax highlighting and indentation guides for @openapi tags in JSDoc comments.

Features

• YAML Syntax Highlighting: Full syntax highlighting for YAML content in @openapi blocks
  • Keys, strings, numbers, booleans, and colons all properly colored
  • Matches VS Code's standard YAML file colors
• Indentation Guides: Visual guides showing YAML structure
  • Vertical lines at each indentation level
  • Active guide highlighting (brighter line for current cursor position)
  • Starts from the base declaration (API route)
• Smart Key Detection: Properly highlights API paths (/api/users), response codes (200, 404), and all YAML keys
• Multi-language Support: Works with JavaScript (.js, .cjs, .mjs), TypeScript (.ts), JSX (.jsx), and TSX (.tsx) files
• Customizable Colors: Configure colors for light and dark themes separately via VS Code settings
• Real-time Updates: Colors and guides update instantly as you type and when you move your cursor

Usage

Simply write your OpenAPI/Swagger documentation in JSDoc comments using the @openapi tag:

/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: Get all users
 *     tags:
 *       - Users
 *     responses:
 *       200:
 *         description: Success
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 */
router.get('/api/users', async (req, res) => {
  // Implementation
});

Example

The extension works with various JSDoc formats:

/**
 * User endpoint handler
 * @openapi
 * /api/user/{id}:
 *   get:
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 */
static async myEndpointHandler(req, res) {
  // Your code here
}

Installation

From Source

1. Clone this repository
2. Open the folder in VS Code
3. Press F5 to open a new Extension Development Host window
4. Test the extension with your JavaScript/TypeScript files

Building VSIX Package

npm install -g vsce
vsce package

Then install the .vsix file:

• Open VS Code
• Go to Extensions view (Ctrl+Shift+X)
• Click the "..." menu and select "Install from VSIX..."
• Select the generated .vsix file

Configuration

You can customize the colors for both light and dark themes through VS Code settings:

1. Open Settings (Ctrl+, or Cmd+,)
2. Search for "JSDoc OpenAPI"
3. Configure colors for each element:

Light Theme Colors

• jsdocOpenapi.colors.light.key - YAML keys (default: #0000FF)
• jsdocOpenapi.colors.light.string - String values (default: #A31515)
• jsdocOpenapi.colors.light.number - Numbers (default: #098658)
• jsdocOpenapi.colors.light.boolean - Booleans (default: #0000FF)
• jsdocOpenapi.colors.light.colon - Colons (default: #000000)
• jsdocOpenapi.colors.light.indentGuide - Indentation guides (default: rgba(0, 0, 0, 0.18))
• jsdocOpenapi.colors.light.activeIndentGuide - Active guide (default: rgba(0, 0, 0, 0.40))

Dark Theme Colors

• jsdocOpenapi.colors.dark.key - YAML keys (default: #569CD6)
• jsdocOpenapi.colors.dark.string - String values (default: #CE9178)
• jsdocOpenapi.colors.dark.number - Numbers (default: #B5CEA8)
• jsdocOpenapi.colors.dark.boolean - Booleans (default: #569CD6)
• jsdocOpenapi.colors.dark.colon - Colons (default: #D4D4D4)
• jsdocOpenapi.colors.dark.indentGuide - Indentation guides (default: rgba(255, 255, 255, 0.18))
• jsdocOpenapi.colors.dark.activeIndentGuide - Active guide (default: rgba(255, 255, 255, 0.40))

Requirements

• Visual Studio Code 1.60.0 or higher
• Built-in YAML language support (included with VS Code)

Testing

Open example.js and compare it side-by-side with example.yaml to see the matching syntax highlighting.

To test:

1. Press F5 to launch Extension Development Host
2. Open example.js in the new window
3. Verify YAML content after @openapi has syntax highlighting and indentation guides
4. Move your cursor through different indent levels to see active guide highlighting

Troubleshooting

No YAML highlighting visible

1. Reload the window: Press Ctrl+Shift+P → "Developer: Reload Window"
2. Check file type: Ensure file has .js, .ts, .cjs, .mjs, .jsx, or .tsx extension
3. Inspect scopes: Use "Developer: Inspect Editor Tokens and Scopes" to verify source.yaml scope is present

Only @openapi tag is highlighted

This means the default JSDoc highlighting works but our grammar injection doesn't:

• Verify package.json and grammar file have matching scopeName
• Check Extension Host output for errors (Ctrl+Shift+U → "Extension Host")
• Restart the Extension Development Host (close and press F5 again)

Partial or incorrect highlighting

• Ensure each JSDoc line starts with * (space-asterisk-space)
• Check YAML indentation is consistent (use spaces, not tabs)
• Verify YAML syntax is valid

Known Issues

• The extension currently supports @openapi tag. Other similar tags can be added by modifying the grammar file.
• Indentation guides assume 2-space indents (configurable via editor.tabSize)

Contributing

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

Author

SimPleased - GitHub

License

GNU General Public License v3.0 or later (GPL-3.0-or-later)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See the LICENSE file for details.