JSON을 JSDoc 주석으로 변환 — Numio

JSON 샘플로 키마다 @property 한 줄씩 있는 JSDoc @typedef 주석을 만듭니다. 중첩 키는 address.city 같은 점 경로, 배열 항목의 키는 name[].key, 선택적 키는 [대괄호]를 사용합니다.

순수 JavaScript 프로젝트에서 API 응답에 대한 편집기 자동 완성을 얻습니다.

JSON

JSDoc

이럴 때 사용하세요

순수 JavaScript 프로젝트에서 API 응답에 대한 편집기 자동 완성을 얻습니다.
TypeScript로 옮기지 않고도 JSON 데이터에 // @ts-check 타입 검사를 켭니다.

사용 방법

JSON 객체를 편집기에 붙여 넣습니다.
오른쪽의 @property 줄을 확인합니다. 타입은 샘플 값에서 나오며, 예를 들어 tags는 string[], address는 object입니다.
주석을 복사해 typedef 이름을 json에서 실제 이름으로 바꾸고 @type {YourName}으로 사용합니다.

JSON 입력

{
  "id": 42,
  "name": "Ada",
  "tags": ["math", "poetry"],
  "address": { "city": "London", "zip": "NW1" },
  "orders": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B7", "qty": 1, "gift": true }
  ],
  "deletedAt": null
}

JSDoc @typedef

/**
 * @typedef {object} json
 * @property {number} id
 * @property {string} name
 * @property {string[]} tags
 * @property {object} address
 * @property {string} address.city
 * @property {string} address.zip
 * @property {object[]} orders
 * @property {string} orders[].sku
 * @property {number} orders[].qty
 * @property {boolean} [orders[].gift]
 * @property {null} deletedAt
 */

세부 정보 및 제한 사항

주석은 브라우저에서 생성되며 서버로 데이터를 보내지 않습니다. 설정은 없습니다.

배열의 모든 항목이 병합됩니다. 일부 항목에만 있는 키는 [orders[].gift]처럼 대괄호로 감싸 선택적으로 씁니다.

항상 null인 값은 {null} 타입이 되고, 실제 값과 함께 있는 null은 {string|null} 같은 유니언이 됩니다. 빈 배열은 {Array} 타입입니다.

001 같은 ID는 입력에서 문자열로 유지하세요. 숫자로 파싱되면 앞의 0이 사라집니다.

FAQ

객체 배열은 어떻게 문서화되나요?

배열은 object[] 타입이 되고, 항목의 키는 orders[].sku 같은 name[].key 경로로 나열되며 모든 항목의 키가 합쳐집니다.

루트가 배열인 JSON도 변환할 수 있나요?

예. 항목 구조는 속성을 가진 @typedef {object} jsonItem이 되고, 이어서 배열을 위한 @typedef {jsonItem[]} json이 나옵니다.

TypeScript가 생성된 typedef를 이해하나요?

예. checkJs나 // @ts-check가 켜져 있으면 TypeScript는 .js 파일에서 중첩 @property 경로가 있는 @typedef를 읽습니다. 단독 {null}은 먼저 실제 타입으로 바꾸세요.

사양 및 참고 자료

JSDoc: @typedef