mdconfでJSON SchemaとSwaggerを書いていく
こんにちは。齋藤です。
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
