mdconfでJSON SchemaとSwaggerを書いていく

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは。齋藤です。

markdown driven configuration と書かれている マークダウン形式のファイルからJSONを吐き出すツール mdconf を使って JSON Schema、Swagger 2.0 の JSONファイルを吐き出してみました。

今回の記事では、以下の内容について記述しています。

  • package.json の JSON Schema を markdownで書いてみる
  • Swagger の JSON を markdownで書いてみる

なお、実際に利用する際にはしっかりと検討した上でご利用ください。 書いていくぞ!!

はじめに

この記事は、API仕様を書く調査のその一環です。

色々調べた結果、個人的な気持ちとしては以下の通りです。

  • API Blueprintは、エコシステムがもっと進化していくと良さそう
  • Swagger (OpenAPI) は色々ツールが揃ってるよね ⇨ Swagger (OpenAPI) 3.0 はシンプルになってる
  • RAMLはごめんなさい、あんまり調べきれてはいません

というわけで、今回は Swagger の JSON を書くのを mdconf でできないか、試しました。

今回使った mdconf を使って変換するコードは以下のものです。

JSON Schemaを書いてみる

まずはJSON Schemaをmdconf形式で書いてみます。

npm の package.json のJSON Schemaを書いてみた。

項目だけ見ると確かにそれっぽい。

実際のファイルはこちらです。

実は package.json の JSON Schemaなどは schemastoreというサイトにあったりします。

package.json の JSON Schemaはここにあります。 ちなみにVSCodeはここからJSON Schemaを取り込んで、何種類か中に持っています。 そのJSON Schemaを使って補完してくれたりします。便利。

Swagger 書いてみる

今度は 余所様 の Swagger の定義を参考に
Swagger の JSON を mdconf 形式で書いて見ました。

実際のファイルはこちらです。

割と使えそうでしょうか。どうでしょう。

ちなみに、上記の状態では .basePath の キーが basepath といったように小文字になってしまいます。
実際にSwaggerのJSONファイルとして用いる場合は書き換えてください。

まとめ

今回はmdconfを使って JSON Schema 、Swagger 2種類のJSONを生成する markdown を書いてみました。
非常に面白いツールですが、現状の書いてみて思ったことをまとめてみました。

  • string しか値に設定できない
       additionalProperties の値 とかは bool値で困った(今回はサンプルから削っています)
  • top levelに 値を入れるのが辛い
  • header や list で object の key を指定する場合に全て小文字になる
  • code blockなどは list 形式で値が設定される
  • list の nested に 対応していない
       これに関しては 一応issueがあったりします。
  • table の対応はまだリリースされてない
  • 階層構成を追うのに Qiita にあるような、脇に出てくる目次がないと厳しいかも

用途に合ってないのか、実際に使うには厳しい印象を受けましたが、非常に面白いツールだと思います。
ちょっとした設定ファイル生成に使って見てはいかがでしょうか。

「書いていくぞ!」と強気に出てみましたが、普通に Swagger を書こうと思いました。

ちなみに サンプルの JSON があるなら JSON Schema を吐くだけなら quicktype と使うと良いです。
quicktype の利用方法については、弊ブログに紹介記事があるのでそちらをご覧ください。

下のような形で、JSON Schemaの生成が可能です。

quicktype -l schema -o schema.json package.json

Special Thanks