※ "JSON Schema에서 문서 생성"이 아니라 "문서에서 JSON Schema 생성"입니다.

개시하다

SDD(Specification Driven Development)에서는 스웨거·램 등 API 정의 포맷, JSON Scheema 등 JSON Object 정의 포맷 등을 자주 사용하는데, 이 포맷에서 코드를 생성하면서 문서를 생성한다.규격과 실장의 괴리를 없애는 장점이 있다.
일반적으로 JSON(YAML)을 소스로 관리하고 HTML 문서를 생성하지만 엔지니어 이외의 Stage holder가 있는 환경에서 사용할 경우 HTML의 호스트 서버를 준비하십시오.계속 업데이트하는 작업을 준비하면 좀 번거로울 거예요.
따라서 이번에는 JSON에서 문서를 생성하는 것이 아니라 문서에서 JSON을 생성함으로써 상술한 해결 방법을 시도합니다. 문서는 태그로 기술되어 있습니다. GiitHub 등은 태그를 HTML로 변환하여 표시합니다.기록된 태그 자체가 문서다. 즉, 문서는 생성된 것이 아니라 원본 파일이기 때문에 GiitHub 등으로 원본 파일을 관리하면 언제든지 최신 문서를 조회할 수 있다.

mdconf를 사용하여 JSON 확인

예를 들어, 다음 JSON Scheema를 사용합니다.
user.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "user",
  "type": "object",
  "additionalproperties": "false",
  "required": [
    "id",
    "lastName",
    "firstName",
    "state"
  ],
  "properties": {
    "id": {
      "type": "number"
    },
    "lastname": {
      "type": "string"
    },
    "firstname": {
      "type": "string"
    },
    "state": {
      "type": "number",
      "enum": [
        "1",
        "2"
      ]
    }
  }
}

JSON으로 표시된 것을 지우기 위해서 mdconf.mdconf를 사용하고 #와 -를 사용하여 속성과 값을 표시합니다. 이 모든 줄은 퍼스의 대상에 있지 않으며 자유롭게 기술할 수 있습니다.
다음은 위의 JSON Schema에서 생성된 태그에 대한 설명입니다.
user.md

- $schema: http://json-schema.org/draft-04/schema#

- id: user

- type: object

- additionalProperties: false

# required

- id

- lastName

- firstName

- state

# properties

## id

user id

- type: number

## lastName

user's last name

- type: string

## firstName

user's first name

- type: string

## state

user state

- type: number

### enum

active

- 1

inactive

- 2

GiitHub에서 다음과 같이 Skima 정의는 이해하기 쉬운 문서로 이 문서를 유지보수합니다.

다음은 코드를 이용하여 이 표시를 검증한 예입니다.mdconf를 통해 간단하게 세척할 수 있습니다.

import fs from 'fs'
import path from 'path'
import isMyJsonValid from 'is-my-json-valid'
import parse from 'mdconf'
import assert from 'assert'

// マークダウンを読み込み, JSON にパース
const mdFilePath = path.resolve(__dirname, 'user.md')
const schema = parse(fs.readFileSync(mdFilePath, 'utf8').toString()))

const userData = { id: 1, lastName: 'Yamada', firstName: 'Taro', state: 1 }

// データが想定しているフォーマットかどうか検証
const validator = isMyJsonValid(schema)
assert(validator(userData), validator.errors)

끝말

표기 아래 Schema 정의를 기술함으로써 문서로도 사용할 수 있고 코드로도 직접 사용할 수 있다. 좀 적극적이지만 Swagger나 RAML 등에서도 통용되는 방법이니 관심 있는 분들은 꼭 시도해 보세요.