Swagger JSDoc 中的 VSCode 缩进

Question

我在 Express 中使用 swagger-jsdoc。使用这个库来描述一个 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 cmets 中的 JSON 配合使用。

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

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

Answer 2

在使用 swagger-jsdoc 编写 YAML 规范时，我创建了 a simple extension 来解决这个特定问题。

所有内容都记录在自述文件中，但基本上你是这样编写规范的（允许自动缩进）

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

选择您的评论区，按cmd + shift + P (MacOS) 或ctrl + shift + P (Windows) 并搜索Format swagger-jsdoc comment。

扩展将：

• 运行prettier 来修复/捕获缩进错误
• 在每行的开头添加一个星号
• 用格式化的评论块替换您的评论块
• 尊重块的任何缩进

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