(プレゼンテーションのスライドはこちらからご覧いただけます。) 開発者エクスペリエンスとは、一般的なユーザーエクスペリエンスの延長であり、開発者と彼らがAPIを操作する際の体験を重視するものです。優れたAPI開発者エクスペリエンスは、技術文書の作成にとどまりません。最終的な利用者がAPIを成功裏に統合し、操作するのに役立つすべての適切なリソースを提供することです。
DXにおけるドキュメントの役割
適切に設計された開発者エクスペリエンスの中心には、APIドキュメントがあります。 APIドキュメントとは、APIを成功裏に利用し、統合するために必要な情報です。これは、APIの利用方法をよりよく理解するための技術文書、コードサンプル、例の形をとります。 SmartBearの2016年APIレポートによると、APIを開発する組織の75%が正式なドキュメント作成プロセスを持っており、46%が組織にとって高い優先順位であると回答しています。 API利用者がアプリケーションに迅速に採用できるようにする簡潔で明確なドキュメントは、APIの採用を促進したい組織にとって、もはやオプションではありません。
優れたドキュメントは容易な作業ではない
多くのAPIチームにとって、ドキュメント作成は依然として退屈で時間のかかる作業です。これは、APIの新しいバージョンがリリースされるたびに手動で更新される静的なドキュメントに依存するチームにとっては特に当てはまります。 しかし、組織がAPIをドキュメント化する方法にもいくつかの重要な変化がありました。これらの変化が最も顕著なのは、SwaggerのようなAPI記述形式の広範な採用です。 Swaggerは、開発者やチームがRESTful Webサービスを設計、構築、ドキュメント化、および利用できるオープンソースのAPIフレームワークです。Swaggerフレームワークがこれほどまでに大規模な採用を得た最大の理由の1つは、インタラクティブなドキュメントを生成する機能です。このドキュメントにより、開発チームであろうと最終的な利用者であろうと、実装ロジックがなくてもAPIのリソースを視覚化し、操作することができます。 この自動生成されたドキュメントは、開発チームがカスタマイズし、APIを操作するためのより包括的なユーザーマニュアルを作成するための中心的なリソースとなります。
ドキュメントに Swagger を追加する
Swagger を初めて使用する場合でも、API 設計に既にフレームワークを使用している場合でも、API ドキュメントを改善する方法についてまだ疑問があるかもしれません。顧客に愛される API ドキュメントを作成するには多少の労力が必要ですが、その投資は、優れた開発者エクスペリエンス、より簡単な実装、そして API の採用率の向上という形で大きな利益をもたらすでしょう。 今月、API ドキュメントに関する無料トレーニングを開催しました。API 開発者エクスペリエンス：なぜ重要なのか、そして Swagger を使った API ドキュメント作成がどう役立つのか。 このウェビナーでは、優れた開発者エクスペリエンスについて詳しく説明し、API を使用する開発者に最適なエクスペリエンスを提供すべき理由と方法に焦点を当てました。また、Swagger が API 設計とドキュメントの状況をどのように変えたかについても説明し、最後に SwaggerHub の統合 API 開発プラットフォームで Swagger を使用した API ドキュメントの優れたプラクティスをいくつか紹介します。 このウェビナーで期待できること：
- 開発者エクスペリエンス (DX) とは？
- API が優れた DX を持つとはどういう意味か？
- 優れた DX の文脈における API ドキュメント？
- Swagger フレームワークの紹介
- Swagger と SwaggerHub を使用したユーザビリティの観点からの API 設計