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

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

package.json — npm 의 schema

VS Code 에서 package.json 을 열고 아무 필드에나 마우스를 올려봐. 거기 뜨는 autocomplete 와 설명은 커뮤니티가 관리하는 JSON Schema https://json.schemastore.org/package.json 에서 오는 거야. 파일 맨 위에 "$schema": "https://json.schemastore.org/package.json" 을 적어두면 연결을 대놓고 못 박는 셈이야. 에디터에 따라 이걸 요구하기도 하는데, 대부분은 파일 이름만 보고 알아채.

tsconfig.json — TypeScript 의 계약

여기도 똑같아. https://json.schemastore.org/tsconfig.json 를 한 번 통독하면 tsconfig 의 모든 필드가 뭘 하는지, 기본값이 뭔지, 어떤 제약이 붙는지가 잡혀. autocomplete 가 바로 이걸 보고 뜨는 거라, 어떤 문서보다 정확해.

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

OpenAPI 3.x 는 components.schemas 안에서 JSON Schema 를 써 (방언이 살짝 다르지만 거의 그대로 호환돼). Stoplight, Redoc, Swagger UI 같은 도구가 그 schema 로 문서 페이지를 그리고, 클라이언트를 뽑고, 게이트웨이에서 요청과 응답을 검증해. API 계약은 JSON Schema 안에 살아 있고, 나머지는 전부 그걸 그려낸 결과물이야.

'이 필드 뭐 하는 거지' 싶을 때: 처음 보는 config 를 만나면 (새 linter, 새 bundler, 새 CI 도구) Schema Store 에서 그 schema 부터 찾아봐. schema 에 달린 description, enum, default 가 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