Ad

VSCode Indent In Swagger JSDoc

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

Ad

Answer

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


Ad
source: stackoverflow.com
Ad