Generated JSON schema description missing some data

[liangskyli]

[email protected] is error, but [email protected] is correct.

error in: description output

Expected output： "description": "This file was auto-generated by @aaa/bbb.\nDo not make direct changes to the file.", actual output： "description": "This file was auto-generated by",

full code:

/**
 * This file was auto-generated by @aaa/bbb.
 * Do not make direct changes to the file.
 */

export interface paths {
  '/root/v4/getQueryParams1-v4': {
    get: {
      parameters: {
        query: {
          /** @description activityBases */
          activityBases: {
            /** @description 活动名称 */
            activityName: string;
          }[];
        };
      };
      responses: {
        /** @description Success */
        200: {
          content: {
            'text/plain': string;
          };
        };
      };
    };
  };
}

actual output：

{
  "description": "This file was auto-generated by",
  "type": "object",
  "properties": {
    "/root/v4/getQueryParams1-v4": {
      "type": "object",
      "properties": {
        "get": {
          "type": "object",
          "properties": {
            "parameters": {
              "type": "object",
              "properties": {
                "query": {
                  "type": "object",
                  "properties": {
                    "activityBases": {
                      "description": "activityBases",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "activityName": {
                            "description": "活动名称",
                            "type": "string"
                          }
                        },
                        "required": ["activityName"]
                      }
                    }
                  },
                  "required": ["activityBases"]
                }
              },
              "required": ["query"]
            },
            "responses": {
              "type": "object",
              "properties": {
                "200": {
                  "description": "Success",
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "object",
                      "properties": {
                        "text/plain": {
                          "type": "string"
                        }
                      },
                      "required": ["text/plain"]
                    }
                  },
                  "required": ["content"]
                }
              },
              "required": ["200"]
            }
          },
          "required": ["parameters", "responses"]
        }
      },
      "required": ["get"]
    }
  },
  "required": ["/root/v4/getQueryParams1-v4"],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Expected output：

{
  "description": "This file was auto-generated by @aaa/bbb.\nDo not make direct changes to the file.",
  "type": "object",
  "properties": {
    "/root/v4/getQueryParams1-v4": {
      "type": "object",
      "properties": {
        "get": {
          "type": "object",
          "properties": {
            "parameters": {
              "type": "object",
              "properties": {
                "query": {
                  "type": "object",
                  "properties": {
                    "activityBases": {
                      "description": "activityBases",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "activityName": {
                            "description": "活动名称",
                            "type": "string"
                          }
                        },
                        "required": ["activityName"]
                      }
                    }
                  },
                  "required": ["activityBases"]
                }
              },
              "required": ["query"]
            },
            "responses": {
              "type": "object",
              "properties": {
                "200": {
                  "description": "Success",
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "object",
                      "properties": {
                        "text/plain": {
                          "type": "string"
                        }
                      },
                      "required": ["text/plain"]
                    }
                  },
                  "required": ["content"]
                }
              },
              "required": ["200"]
            }
          },
          "required": ["parameters", "responses"]
        }
      },
      "required": ["get"]
    }
  },
  "required": ["/root/v4/getQueryParams1-v4"],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

[veithlukas]

@liangskyli for me escaping the @ with \ helped to fix this issue

[raineorshine]

This is a breaking change introduced in #564 with the upgrade to Typescript v5.

It appears that the Typescript API now parses inline tags from jsdoc comments.

symbol.getJsDocTags():

[
  {
    "name": "aaa",
    "text": [
      {
        "text": "/bbb.\nDo not make direct changes to the file.",
        "kind": "text"
      }
    ]
  }
]

Thus leaving symbol.getDocumentationComment() to only return the first part of the comment:

[ { text: 'This file was auto-generated by', kind: 'text' } ]

Though this seems like wrong behavior, it is probably expected since this is indeed how Typescript parses jsdocs now, for example, in VS Code:

In my tests, prefixing @ with \ does not actually escape it, since \ ends up in the output. It just prevents @ from being parsed as a tag since it is no longer at the beginning of a word boundary. Therefore, surrounding it with quotes or back ticks might make more sense:

/**
 * This file was auto-generated by `@aaa/bbb`.
 * Do not make direct changes to the file.
 */