APIデザインとSwagger (OpenAPI) 仕様に関して、Arnaud Lauretほど情熱を持っている人物はほとんどいません。彼は*API Handyman* (@apihandyman) として最もよく知られています。Arnaudは、プログラマーとプロジェクトマネージャーの両方として約13年間ITバンキングに従事し、現在はAXA BanqueでITアーキテクトとしてAPIプロジェクトとガバナンスに取り組んでいます。
9月に、ArnaudはAPI Stylebookを公開しました。これは、厳選され分類されたリソースに素早く簡単にアクセスできるようにすることで、APIデザイナーがAPIデザインの課題を解決し、APIデザインガイドラインを構築するのに役立つことを目的としています。Arnaudは、OpenAPI仕様の記述に関する10部構成のSwaggerチュートリアルの作成者でもあります。彼のチュートリアルは、SwaggerのオープンソースツールやSwaggerHubを使い始めるすべての人にとって貴重なリソースです。
今月初め、SmartBear本社で開催されたAPIエキスパートパネル「2017年のAPI戦略の策定」にArnaudをお招きする光栄に浴しました。パネルに先立ち、私たちはArnaudと座って、Swaggerを使い始めた経験や、優れたAPIデザインの共通の特性について詳しく聞きました。
Swaggerを使い始めた経験について教えていただけますか？
数年前、APIプロジェクトを開始し、APIのドキュメントを作成したかったので、コードからドキュメントを生成するためにSwaggerアノテーションを使い始めました。当時は、このアノテーションの背後にあるのがOpenAPI仕様というフォーマットだとは知りませんでした。開発者にアノテーションの書き方を十分に指示しなかったため、最初の結果はドキュメントとしてあまり使えませんでした。
その頃、Swagger 2.0が登場し、新しい仕様、エディター、YAMLの使用が導入されました。ドキュメントはコード内にあったため、更新が非常に複雑でした。そこで、既存の生成されたドキュメントを取得してSwagger 2.0に変換することで、このフォーマットをいじり始め、解析と操作が非常に簡単であることに気づきました。
ドキュメントにあった多くの問題を修正する別のモジュールを作成しました。それが、私がこのフォーマットを徹底的に使いたいという意欲を引き起こしたのです。当時は、これで多くのことができると感じていました。私たちは、OpenAPI仕様フォーマットで仕様を書き始めました。設計時に、仕様を解析して、新しく設計されたAPIが私たちのガイドラインに準拠しているか、新しいドキュメントが完全か、すべてに説明があるかなどを確認するコントロールを記述する予定でした。
それは一歩一歩、日々新しいことを発見していくことでした。結局、ブログで10部構成のチュートリアルを執筆することになりました。この仕様の最も重要な点は、非常にシンプルで、解析して何かをするのに複雑なものは何も必要ないということです。
REST APIに見られる一般的な設計特性/ガイドラインは何ですか？
すべてのガイドラインは、REST APIを作成したいということに焦点を当てています。REST APIとは何でしょうか？リソースがあり、HTTPプロトコル、適切なHTTPステータスなどを使用する必要があります。それらは異なる方法で話をしますが、すべて同じことを非常に技術的な観点から同じように説明しています。この質問をされたとき、彼らが本当の問題、つまりAPIが機能を提供しているかどうかをどう判断するかについて話していないことに気づきました。単にHTTPプロトコルでリソースを提供しているだけではありません。技術的な観点からAPIデザインの枠組みを設定する必要があるため、これらの種類のドキュメントが必要です。
しかし、APIを設計する必要があるすべての企業は、機能的な観点からAPIを設計する方法に関する機能的なガイドラインも必要だと私は考えます。それについて書かれた本はありますが、これらのガイドラインはすべて非常に技術的なものです。
さらに詳しく知りたいですか？
Arnaudの最新リソースはAPIHandyman Blogでご確認ください。OpenAPI仕様を始めますか？こちらのOpenAPIリソースセクションをご覧ください。