VSCode 在 Swagger JSDoc 中缩进

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 一起使用。

在第一个示例中，我写了正常的 JSON，VSCode 缩进，然后我使用列 select 将 * 放在每行前面

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

我创建了 a simple extension 来解决在使用 swagger-jsdoc.

编写 YAML 规范时的这个特殊问题

README 中记录了所有内容，但基本上您是这样编写规范的（允许自动缩进）

/**
 * 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 您的评论区，按 cmd + shift + P (MacOS) 或 ctrl + shift + P (Windows) 并搜索 Format swagger-jsdoc comment.

扩展程序将：

运行 prettier 到 fix/catch 缩进错误
在每行的开头添加一个星号
将您的评论块替换为格式化的评论块
尊重块的任何缩进

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

VSCode 在 Swagger JSDoc 中缩进

VSCode indent in Swagger JSDoc

node.js

jsdoc

swagger

visual-studio-code

openapi