VOYAGE Lighthouse Studio の海老原 (@co3k) です。先日 30 歳になった記念としてタイトルはオヤジギャグです。 さて、普段は 神ゲー攻略 というゲーム攻略サイトを運営しているのですが、とある派生サービスを立ち上げるにあたり、 Web API スキーマ定義を gRPC に基づく形式の Protocol Buffers で書き、 protoc-gen-swagger プラグインを介して OpenAPI 定義ファイルとして生成する、というアプローチを採りました。 yugui さんの素晴らしい記事、「今さらProtocol Buffersと、手に馴染む道具の話」によってスキーマ定義言語としての Protocol Buffers がにわかに注目を浴びて以降、似たようなことをやりたいという方もいらっしゃるのではないでしょうか。 ところが、おそらく単体で protoc-g
CTO兼福岡オフィス立ち上げ担当として新アプリを作っている@edvakfです。 JSON APIを開発しているとこういう問題がありがちですよね。 仕様どおりにAPIの形式を作ったはずだけどなんか自信が持てない テストでいくつかのキーが存在するかの簡単なチェックはしてるつもりだけど、全部チェックするのは大変すぎる APIのControllerやViewをリファクタリングしたらレスポンスの形が変わってアプリがめっちゃクラッシュし始めた というのが怖くて誰もリファクタリングできなくなった APIドキュメントがメンテされない 知らない間にレスポンスのフィールドが増えてたけどドキュメントに書いてない これらを解決したい！と思って試行錯誤したら、スマートに解決することができました。この記事ではRailsのことについて書きますが、考え方は他の言語・フレームワークでも同じです。 なお、今回使ったgemのバ
はじめに Web サービスの運用を続けていくと，依存関係が徐々に複雑になっていきます．そしてメンテナンスするものが増えた結果，それらが相互に乖離していく，といったことが起こりがちです． そこで今回は，JSON Schema のみをメンテナンスしていくことで，動的チェック (バリデーション)，静的チェック (FlowType)，API ドキュメント生成，スタブ作成といった様々な恩恵を享受し，品質と保守性を同時に向上させるアプローチについて書いていきます．この JSON Schema を中心に据えたエコシステムを，__JSON Schema 中心設計__と呼ぶことにします． JSON Schema の仕様については割愛しますので，必要な方は こちら をご覧下さい．また，本記事では JavaScript での事例を紹介しますが，他の言語でも同様の適用ができるかと思います． アプローチ 本記事では
2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
TL;DR JSON Schemaを使ってこういうことが実現可能になった。 ダミーAPIサーバの提供 ドキュメントの自動生成 APIクライアントの動的定義 APIサーバのバリデータの動的定義 APIサーバのレスポンスの自動テスト JSON Schemaとは JSON SchemaというのはあるJSONのデータ構造を記述するための方法および書式の仕様で、 JSON SchemaもJSONで記述される。 これを利用すれば、リソースベースの(=RESTfulライクな)APIの仕様が簡便に記述できる。 例えば、我々のAPIはレシピとユーザというリソースを扱っていて、 それぞれCRUDのAPIを備えており、レシピはidとtitleとdescriptionという属性を持つ、 という旨をJSON Schemaで表現できる。 なんで最近ちょっと流行ってんの Mobile First、 Service Or
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
