Awesome

Table of contents

• Table of contents
• Description
• Usage
  • Installation
  • Formatting comment blocks
    • Example
  • Unformatting
• License

Description

This VSCode extension targets this issue on StackOverflow. Basically, when writing your API spec in YAML with swagger-jsdoc, it is impossible to get automatic indentation and formatting inside the comment blocks. Thus, you end up either writing it in JSON or manually adding spaces/tabs for each line, which is really tedious.

The extension allows you to write your spec inside comment blocks and then format it so swagger-jsdoc can parse it and generate your spec.

VSCode enables automatic indentation when there's no preceding asterisk (*).

/**
 * You won't be able to get automatic indentation here
 * or here
 * 
but you'll
  get it here,
  when there's no asterisk
    preceding the line
 */

Usage

Installation

Install the extension from the installation page.

Formatting comment blocks

For the extension to correctly parse your comment block, it should follow the following guidelines:

• The spec has to start with either @swagger or @openapi
• The comment should start with /**
• No line (of the spec only) should start with an asterisk (*)
• It can contain regular comments preceded by an asterisk before the spec
• Before running the extension you must place your cursor within the comment block

Example

Write your spec

/**
 * Spec for the route /auth/register.
 *
@openapi
/auth/register:
  post:
    summary: Register as user
    tags:
      - Auth
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - name
              - email
              - password
            properties:
              name:
                type: string
              email:
                type: string
                format: email
                description: Must be unique
              password:
                type: string
                format: password
                minLength: 8
                description: At least one number and one letter
 */
router.post("/auth/register", authMiddleware.validate, authController.register);

Place your cursor within the comment block, press cmd + shift + P (MacOS) or ctrl + shift + P (Windows) and search for Swagger jsDoc: Format spec.

The extension will:

• Run prettier to fix/catch indentation errors
• Add an asterisk at the start of each line
• Replace your comment block with the formatted one
• Respect any indentation of your block

/**
 * Spec for the route /auth/register.
 *
 * @openapi
 * /auth/register:
 *   post:
 *     summary: Register as user
 *     tags:
 *       - Auth
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - name
 *               - email
 *               - password
 *             properties:
 *               name:
 *                 type: string
 *               email:
 *                 type: string
 *                 format: email
 *                 description: Must be unique
 *               password:
 *                 type: string
 *                 format: password
 *                 minLength: 8
 *                 description: At least one number and one letter
 *
 *
 * More regular comments here
 */
router.post("/auth/register", authMiddleware.validate, authController.register);

Optionally run swagger-jsdoc to generate your spec.

$ yarn swagger-jsdoc -d docs/api/definition.yml src/api/routes/v1/**.ts -o docs/api/specification.yml

Unformatting

It is possible to undo the formatting for easy editing (thanks @doctorfred). Works the same as formatting, but instead removes the asterisks so you can edit the spec while being able to indent it.

Place your cursor within the comment block, press cmd + shift + P (MacOS) or ctrl + shift + P (Windows) and search for Swagger jsDoc: Unformat spec.

Then you can just format it again.

License

MIT