현장의 스키마 — package.json, tsconfig, OpenAPI

이미 JSON Schema 쓰고 있다, 모를 수도

package.json — npm 의 schema

VS Code 에서 package.json 열어. 아무 필드 hover. autocomplete 와 인라인 docs 가 커뮤니티 유지 JSON Schema https://json.schemastore.org/package.json 에서 와. package.json 맨 위에 "$schema": "https://json.schemastore.org/package.json" 추가하면 binding 이 명시적 (일부 에디터는 요구, 대부분은 파일 이름으로 인식).

tsconfig.json — TypeScript 의 계약

같은 이야기: https://json.schemastore.org/tsconfig.json. 한 번 읽으면 모든 tsconfig 필드의 목적, 기본값, 제약을 이해해. autocomplete 의 source of truth 라서 docs 보다 나아.

OpenAPI — 엔드포인트 묘사하는 schema

OpenAPI 3.x 가 components.schemas 안에서 JSON Schema 사용 (약간 dialect, 대부분 호환). Stoplight, Redoc, Swagger UI 같은 도구가 그 schema 를 문서 페이지로 렌더링, 클라이언트 생성, 게이트웨이에서 요청/응답 검증. API 계약이 JSON Schema 에 살고; 나머지는 렌더링.

'이 필드 뭐 함' 무브: 모르는 config (새 linter, 새 bundler, 새 CI 도구) 만났을 때, Schema Store 에서 schema 찾아. schema 의 description, enum, default annotation 이 보통 README 보다 명확.

Code

package.json autocomplete 켜기·json

{
  "$schema": "https://json.schemastore.org/package.json",
  "name": "my-app",
  "version": "1.0.0",
  "description": "A small thing",
  "scripts": {
    "test": "vitest run"
  }
}

OpenAPI schema (안에 JSON Schema)·yaml

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
components:
  schemas:
    User:                    # ← This is JSON Schema
      type: object
      properties:
        id:    { type: integer }
        name:  { type: string  }
        email: { type: string, format: email }
      required: [id, name, email]
paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

schema 에서 TypeScript 타입 생성·bash

# json-schema-to-typescript: schema → .d.ts
npx json-schema-to-typescript user.schema.json > user.d.ts

# OpenAPI → TS 클라이언트
npx openapi-typescript openapi.yaml -o api-types.ts

Exercise

프로젝트의 진짜 package.json 에 "$schema": "https://json.schemastore.org/package.json" 추가. VS Code autocomplete 가 더 날카로워졌는지 (또는 그대로 — 일부 에디터는 파일명으로 추론) 봐. 그 다음 schema URL 브라우저에서 열고 훑어. 한 번도 안 쓴 package.json 필드 하나 골라서 뭐 하는지 읽어. Schema Store 가 학습 도구도 됨.

현장의 스키마 — package.json, tsconfig, OpenAPI

이미 JSON Schema 쓰고 있다, 모를 수도

package.json — npm 의 schema

tsconfig.json — TypeScript 의 계약

OpenAPI — 엔드포인트 묘사하는 schema

Code

External links

Exercise

Progress

댓글 0