VSCode indent in Swagger JSDoc

Question

I'm using swagger-jsdoc with Express. Using this lib to describe an api end-point I use following lines in JSDock block in YAML:

/**
 * @swagger
 * /users:
 *    post:
 *      summary: Register a user
 *      tags: [Users]
 *      description: Register a new user and return its cookie token (connect.sid)
 *      parameters:
 *        - in: body
 *          name: body
 *          schema:
 *            type: object
 *            required: [login, password, confirm]
 *            description: user's credential
 *            properties:
 *              login:
 *                type: string
 *                minLength: 3
 *                maxLength: 10
 *              email:
 *                type: string
 *              password:
 *                type: string
 *                minLength: 6
 *              confirm:
 *                type: string
 *      responses:
 *        200:
 *          description: OK
 *          schema:
 *            $ref: '#/components/schemas/AuthState'
 *        422:
 *          $ref: '#/components/responses/UnprocessableEntity'
 */

router.post('/', usersController.register);

But the problem is that VSCode completely ignores indentation when I put a new line, it also doesn't show the level of indentation which makes it really difficult to make specification as every single new line I have to press [tab] to reach needed indentation level. Extensions like rainbow indents don't work either because they orient on vscode indents.

Are there any settings or extensions I could use to work with this? Or maybe I'm using a wrong approach and there are better and more used approaches to work with this with Express? Would like to hear about these as well

Answer 1

I created a simple extension that targets this particular issue when writing YAML specs with swagger-jsdoc.

Everything is documented in the README, but basically you write your spec like this (which allows for automatic indentation)

/**
 * 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);

Select your comment block, press cmd + shift + P (MacOS) or ctrl + shift + P (Windows) and search for Format swagger-jsdoc comment.

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);

Answer 2

Hello for what it's worth I avoid the YAML-indentation-complaining problem by writing the OpenAPI bits with JSON in jsdoc. The swagger-jsdoc package works with JSON in jsdoc comments.

In the first example I've written normal JSON, which VSCode indents, and after that I've used column select to put the * in front of each line

/**
 * @openapi
 * "/abc": {
 *      "get": {
 *         "description": "Welcome to swagger-jsdoc!",
 *         "responses": {
 *            "200": {
 *               "description": "Returns a mysterious string.",
 *               "content": {
 *                  "text/xml": {
 *                      "schema": {
 *                          "$ref": "#/components/schemas/MyResponse"
 *                        }
 *                     }
 *                  }
 *            }
 *         }
 *      }
 *   }
 */
 app.get('/abc', (req, res) => {
    res.send('Hello World!');
});

In the second example I'm able to get JSON indents by only having the * go up to the get method. When writing JSON after that, VSCode gives me indents.

/**
 * @openapi
 * "/123": {
 *      "get": {
            "description": "My numeric endpoint",
            "responses": {
                "200": {
                    "description": "Returns a mysterious number",
                    "content": {
                        "application/json": {
                           "$ref": "#/components/schemas/NumResponse"
                       }
                   }
               }
           }
       }
   }
 */
app.get('/123', (req, res) => {
    res.send(123);
});