|今の職場で働き始めてちょうど一年が経ちました。そこでとても幸運なことに、ある一つのサービスの開発に設計段階からかかわることができました。そのサービスは大まかに分けるとWebアプリケーションのフロント部分(Vue.jsなど)・APIサーバー・データ処理サーバー・AIサーバーと分かれており、自分は主にAPIサーバーを担当していました。APIサーバーはメタデータなどの保存の役割も持っており、フロント・データ処理サーバー・AIサーバーにそれぞれAPIの提供をしています。APIはREST(風)で提供していますが、その数は膨大で、しかも複数人でそれぞれの開発を行うためAPIの仕様に関してコミュニケーションコストをできるだけ低くする必要がありました。そこで始めに導入したのがアプリケーションと差異の出ない動的ドキュメントです。使ってリクエストとレスポンスのバリデーションを厳密に行うようにしました。リクエストでバリデーションをかけるのはフロントからの不正な値を受け付けないためですが、レスポンスでバリデーションをかける理由はドキュメントと実際に返す値がずれてしまうことに開発段階で気づくためです。使った理由は、ある程度複雑なデータに対応できること・JSONファイルで定義するので別ファイルにできること・多くの言語で利用できること・広く使われていることなどです。新しいAPIを作った時には、そのエンドポイント+メソッドに対してドキュメントの書き忘れがないように自動でドキュメントが作成されるようにしています。これはSphinxで静的なドキュメントを作るようなことではなく、Webアプリケーションとして動的に作られます。作成方法は、エンドポイントを定義するときにそれをリスト化しておき、それぞれのエンドポイントの実装(クラス)に必ずスキーマとサンプルを取得するメソッドを用意して、それがなければエラーになるようにしています。...サンプルの実装スキーマのJSONにはサンプル用のキーを作って、それをもとにサンプルを作成するように独自に実装しています。できればここは独自実装ではなくいい感じのライブラリを利用したいところです。できるだけここで作るサンプルはそのままアプリケーションにリクエストとして渡すだけで動くことを目指しています。""}テストでのスキーマ・サンプルの利用テストは様々な入力を想定するべきなのでこのサンプルのJSONを使うだけでは不十分だとは思いますが、自動生成されたリクエストサンプルを入力値として、実際に返ってきたレスポンスとレスポンススキーマを比較するというテストを各APIにひとつ書いておけば、少なくともドキュメント通りに動くかどうかはテストできます。ソースコード内のカスタムドキュメントスキーマとサンプルの表示だけではAPIの詳細な使い方を説明するには不十分だという場合もあるので、カスタムドキュメントをコード内に記述できるようにしています。HTMLに変換したものをスキーマ・サンプルと合わせて表示しています。スキーマに記述していないキーを受け付けるかどうかを指定するものです。入れることで想定していないキーが入力されたときにバリデーションエラーを発生させます。することでよりスキーマを厳格化できます。無ければならないキーを指定ます。これを指定することでキーが不足しているJSONをバリデーションエラーにすることができます。導入で得られたことJSONをデータとして扱いやすくなった扱っているデータの中には機械学習の手順を定義するような複雑なデータもあります。バリデーションをかけることでプログラムを書くことなく複雑なJSONにも対応しやすくなりました。API設計者とデータ設計者が別の人でも開発できた例えば学習手順の定義を記述したJSONをクライアントで作成し、それを保存するだけのAPIがあった場合に、APIの設計者は必ずしも学習手順に精通していなくても精通している人が書いたスキーマを割り当てるだけでAPI自体の開発が可能なため、API設計者とデータ設計者が別の人でも開発ができます。バリデーションが言語やフレームワークに依存しなくなった現在Pythonで書かれているコードをGoで書き直すということをやっていますが、PythonコードでのバリデーションではなくJSONファイルによるバリデーションなので使い回しが可能です。元の記事へitkr.github.iofacebooktwitterRSS。