api-types に気象庁の天気予報 API の型定義を登録したのでアメダスを追加するプルリク募集！
aspida/pathpida/frourio を開発している Solufa です。
REST API リクエストを型安全に行う場合に aspida がとても便利なんですが、せっかく書いた型定義を他のプロジェクトでも共有しようとすると相当に苦労します。
そこで aspida の型定義を npm にいい感じに公開する仕組みとして api-types を開発しました。
$ npm install @api-types/<組織名>-<API名> という形式で利用できるように世界中の API 型定義を登録していく計画です。
まさに REST API 版の DefinitelyTyped ですね。
早速第一弾としてちょっと前にバズった気象庁の天気予報 API の型定義を公開しました。
GitHub: https://github.com/aspida/api-types/tree/master/apis/jma/bosai
npm: https://www.npmjs.com/package/@api-types/jma-bosai
npm に型定義を公開すること自体は api-types が無くても出来るのですが api-types を利用すると以下の利点があります。
-
@api-types/xxxというわかりやすいネームスペースを使える - 型定義から README.md の大部分が自動生成されてラク
- GitHub のドキュメントが充実しているように見えるのでユーザーが気軽に試してくれる
オープンソースを自分で公開した経験があるエンジニアなら共感してもらえると思うのですが npm に公開する作業で最も面倒なのが「ユーザーが安心するクオリティのドキュメントを書くこと」なんですよね。
すごいソフトウェアを公開しても GitHub の README がスカスカだとユーザーは試すこともしてくれません。
技術力が高くてコードを書けるエンジニアでもドキュメント作成は全く別の能力が必要なので大変苦労します。
api-types を使うと一部分だけ自分でマークダウンを書くことが出来て残りは自動生成されるので公開作業がかなりラクです。
DefinitelyTyped の @types/xxx を使うのと同じように @api-types/xxx というわかりやすいネームスペースが付くこともユーザーに安心してもらえる要因になります。
すでに登録がある気象庁の天気予報 API にアメダス追加のプルリクを作成する
DefinitelyTyped と同様にプルリクを出せばすでに api-types に登録済みの型定義を誰でも改善できます。
（複数人が同じ箇所を修正したプルリクを出す可能性もあるので必ずマージされるわけではありません）
現在、気象庁の天気予報 API の型定義が公開されていますが「ひまわり」「降水ナウキャスト」だけがあって「アメダス」が存在していません。
追加するにはまず以下のリポジトリを自分の GitHub に fork します。
fork の次は npm install をしてください。
apis/jma/bosai が気象庁の天気予報 API 専用のディレクトリです。
を参考にしながら apis/jma/bosai/api に型定義を作成すると良いです。
型定義の記述ルールは aspida のドキュメントを参考にしてください。
型定義の追加が完了したらドキュメントを更新します。
$ npm run update jma bosai
fork した自分のリポジトリに Push したあと api-types の master ブランチに向けてプルリクを作成すると完了です。
型定義だけでなく apis/jma/bosai/config.md で README.md の Usage 部分の更新もできます。
自作や既存 API の型定義を登録する
メジャー・マイナー問わず任意の API を新規登録することが可能です。
上記と同様に fork と install をしたあとに
$ npm run add <組織名> <API名>
でディレクトリが作成されます。
型定義や Usage を書いたら
$ npm run update <組織名> <API名>
で更新。自分のリポジトリに Push したあとに api-types の master ブランチに向けてプルリクを作成してください。
プルリクが無事マージされたらこちらでタグを付けて npm にリリースしておきます。
@api-types/<組織名>-<API名> で公開されて誰もがインストールできるようになります。
自分一人しか使っていない API や、サーバーが公開されていない社内 API でも登録可能です。
API の型定義が全世界に公開されることに注意してください。
プライベートで公開したい場合は、以下の記事を参考にして自社の npm ネームスペースを使うと良さそうです。
README のメイン画像を差し替える
README の画像を変更する場合は docs/<組織名> ディレクトリに 1280x720 の jpg/png/gif 画像を設置して config.md に画像ファイル名を記述します。
docs/<組織名> ディレクトリ以下に新しいディレクトリを作るのもOKです。
（GitHub pages を利用しているので master にマージされるまでは README に表示されません）
Push する前にこのサイトで画像を圧縮しておいてください。
今後の展開
TypeScript フルスタックフレームワークの frourio で作ったサービスの API 型定義だけを api-types に投稿できるようなシステムも作りたいところ。
夏ごろにはエラー時の型定義も出来る aspida v2 を公開する予定なのでお楽しみに！
サポート
Netflix を見ながらダラダラ開発している私のツイッターに api-types/aspida の質問・要望をお気軽にください。（ゆるキャン△ SEASON2 はいいぞ）
Discussion