JSON Schema書くのが辛くてgemを作った

github.com

会社のプロジェクトでサーバーサイド開発体験することになった。今まではスマホアプリ専門みたいな感じで、API使う側だった。

API使う側的な不満が結構あって、とりあえずドキュメントと実装の乖離は絶対に無くしたい絶対にみたいなモチベーションが生まれた。

なんかそういう感じのはいくつかあったけど、レスポンス自体の定義にはJSON Schemaを使おうという感じになった。ドキュメントはRAML使ってみようという感じで試してる。

JSON SchemaでAPIとドキュメントの乖離無くす手段として、実装からJSON Schema生成するのとかもある。

JsonWorldでモデルからJSON Schemaを生成する - Qiita

Qiitaで使ってる方法に乗っかるのはとても魅力的だったんだけど、プロジェクトの都合的に、ドキュメントとMockを取り急ぎ用意する必要があって、実装から生成するのはいろいろと辛そうかなと思って、一旦JSON Schema手書きすることにしたけどめっちゃ辛かった。

何が辛いって書くこと多いのが辛いし、なんかparserによってはファイルまたいだ$refを解決してくれないとかでarray"items": {"$ref": "hoge.json#definition/hoge"}みたいなのをやるのにめちゃくちゃ消耗した結果諦めた。

諦めたけどコピペで済ますのも大分辛いということで、yaml書いてJSON Schema生成するぞ!という感じにした。

prmdっていうgemyamlJSON Schema書いてJSON Schema生成してくれんだけど、結局書くのがJSON Schemaなので辛い!という感じだった。

ので雑にyaml書いて雑にJSON Schemaに展開してくれるgemを作った。

# foo.yaml
type: object
properties:
  foo:
    type: string
  bar:
    type: string
    optional: true # default value is `false`
  baz_list:
    type: array
    items:
      include: baz.yaml

# baz.yaml
type: object
properties:
  baz:
    type: string

という感じにfoo.yamlbaz.yaml作って、

$ bundle exec schai --yaml foo.yaml --to foo.json

実行すると↓こんなJSON Schemaを生成してくれる。

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "foo": {
      "type": "string"
    },
    "bar": {
      "type": "string"
    },
    "baz_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "baz": {
            "type": "string"
          }
        },
        "required": [
          "baz"
        ]
      }
    }
  },
  "required": [
    "foo",
    "baz_list"
  ]
}

大分消耗感が減ったんだけど、取り急ぎ使う部分しか書いてないので、まだ色々と足りてない感じする。あとテストがめちゃくちゃ足りてない。

JSON Schema書くの辛いと思って、レスポンスの定義だけJSON Schemaにしようって感じだったんだけど、これ拡張してlinkとかも対応すれば便利なのではーと思った。

全てがJSONになる - ✘╹◡╹✘

これ見て周辺情報漁るとなんかもっといい方法あるのでは〜と思うんだけど、一旦はJSON SchemaとRAMLでAPIのドキュメント作ろうという流れ。

誰か使ってみてください。

あとJSON Schemaからschemaに合うJSON生成してくれるgemで良いのあったら教えて下さい 🙇

2015/07/22 23:02 追記

JSON Schemaから雑にJSON吐いてくれるgem作った - 銀の人のメモ帳

自分でgem書いた

後日譚

僕が考えた最強のAPIドキュメント生成 - 銀の人のメモ帳

結局JSON Schemaから雑にJSON吐いてくれるgemだけ使って、このエントリで紹介したgemは捨てた💀