Question

我将swagger-jsdoc与Express结合使用。使用此库描述api端点时，我在YAML的JSDock块中使用了以下几行：

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

但是问题是，当我放置新行时，VSCode完全忽略了缩进，它也没有显示出缩进的程度，这使得制定规范变得非常困难，因为我必须按[tab]达到所需的缩进级别。像彩虹缩进之类的扩展名也不起作用，因为它们面向vscode缩进。

我可以使用任何设置或扩展名吗？或者，也许我使用了错误的方法，并且有更好，更常用的方法可用于Express？也想听听这些

Answer 1

你好，我通过在 jsdoc 中用 JSON 编写 OpenAPI 位来避免 YAML 缩进抱怨问题。 swagger-jsdoc 包在 jsdoc 注释中处理 JSON。

在第一个示例中，我编写了 VSCode 缩进的普通 JSON，之后我使用列选择将 * 放在每一行的前面

/**
 * @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!');
});

在第二个示例中，我只需将 * 转到 get 方法即可获得 JSON 缩进。之后写 JSON 时，VSCode 给了我缩进。


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

Swagger JSDoc中的VSCode缩进

1 个答案: