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

Not an answer to your question, but I found this https://stackoverflow.com/questions/51413448/ to enable jsdoc comment folding in vscode. I found that useful, hth a bit. — Paolo, Oct 08 '19 at 15:06
@DarkZ have you found a better solution to this? I am facing the same problems right now ... — user3740359, Mar 14 '20 at 21:59
FWIW I found it simpler to work with JSON in there, then the spaces are one less headache. — Mendhak, Apr 22 '21 at 11:54
@Mendhak could you elaborate a little bit more, please? I'm not sure `swagger-jsdoc` allows `json` in `jsdoc` — Darkzarich, Apr 23 '21 at 14:03
@DarkZ I've created an example gist here: https://gist.github.com/mendhak/64189150b80a4e52cc88439c5318a17e Try generating your OpenAPI with that, both should work (I use the JSON way for everything) — Mendhak, Apr 23 '21 at 14:12
@Mendhak tried this and it worked just fine. If I remove the leading asterisk in a jsdoc it will also save indentation level apparently while still compiling just nice. This is what I needed for VSCode, maybe other code editors / IDE keep indentation level even with leading asterisks — Darkzarich, Apr 24 '21 at 06:15
@Mendhak btw, could you write your recommendation as an answer to this question so I could set it as the best answer? — Darkzarich, Apr 24 '21 at 06:20

score 5 · Answer 1 · answered Aug 15 '21 at 17:43

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

is there any way you can format with the astericks there already? — DucksEatTurtles, Jul 01 '22 at 00:39
@DucksEatTurtles Kind of. We released a feature on the latest version that lets you remove the asterisks automatically, edit the spec and then add them back again. You can read more in the [Readme](https://github.com/ajmnz/swagger-jsdoc-indent#unformatting) — ajmnz, Jul 01 '22 at 07:17

score 4 · Accepted Answer · answered Apr 25 '21 at 07:51

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

VSCode indent in Swagger JSDoc

2 Answers2