今日、あらゆる業界の組織が、APIプログラムへの投資によるビジネスと戦略的機会を認識しています。APIはデジタル変革を可能にし、多くのエンジニアリングとビジネスの可能性への扉を開きます。
しかし、APIエコノミーの成長は、APIを構築しているチームにとって新しい考え方をも必要とします。エンドユーザーがAPIを使用することの価値を理解せず、使用を開始するために必要なリソースを利用できない場合、最高のAPIプログラムでさえ失敗します。単にAPIが存在するだけでは不十分です。優れたAPI開発者エクスペリエンスも必要です。
API開発者エクスペリエンスとは？
API開発者エクスペリエンスは、一般的なユーザーエクスペリエンス（UX）の拡張です。それは、開発者がAPIとやり取りする際のすべてのエクスペリエンスの総体です。優れたAPI開発者エクスペリエンスは、技術文書を超えています。それは、エンドユーザーがAPIを理解し、APIを成功裏に使用できるようにするための適切なリソースを提供することに関わるものです。
API開発者エクスペリエンスが重要な理由
今日の最新のソフトウェアの世界では、平均的な技術ユーザーは、組織が実装することを決定するツールやプラットフォームに関して、非常に大きな購買力を持っています。Forresterの主席アナリストであるJeffrey Hammond氏によると、ソフトウェアチーム内での採用パターンは開発者へとシフトしており、彼らにソリューションの採用を妨げるか、促進する力を与えています。
これは、ソフトウェア製品の技術的な採用者が、製品の採用と購入の意思決定者になっていることを意味します。そのため、今日のハイパーコネクテッドで競争の激しいエコシステム、特にAPIエコノミーにおいては、製品を技術的な採用者によって簡単に消費できるようにすることが不可欠です。
優れたAPI開発者エクスペリエンスの秘訣
優れた開発者エクスペリエンスを提供する場合、高性能で使いやすいAPIに代わるものはありません。開発者エクスペリエンスは、常にチームが使用したいと望み、安全に統合できると信頼できる信頼性の高いAPIを提供することから始まります。
優れた開発者エクスペリエンスを提供するための重要な要素は、正確かつ最新のAPIドキュメントを提供することです。APIドキュメントとは、APIを正常に消費および統合するために必要な情報です。これは、技術文書、コードサンプル、APIの消費方法をよりよく理解するための例などの形式をとる可能性があります。
今日、最も有名で広く採用されているAPIを開発している企業は、APIの充実した人間に優しいドキュメントに投資しています。Facebook、YouTube、Microsoft、PayPal、DropBoxなどの企業は、内部および公開APIを使用して技術的なオーケストレーションと戦略的な成長を推進しており、ドキュメントをAPI開発者エクスペリエンスの中心に置いています。
APIドキュメントの取り組みを始めるには？
ドキュメントを中核とした優れた開発者エクスペリエンスを提供することは、APIチームにとってこれまで以上に容易になりました。過去には、チームはPDFや手動で更新されるウェブページなど、静的なドキュメント形式に依存する必要がありましたが、現在ではドキュメントワークフローを自動化し、APIの消費をスムーズで簡単なプロセスにするインタラクティブなAPIドキュメントを構築するソリューションがあります。
組織がAPIを文書化する方法は大きく変化しています。これらの変化は、OpenAPI仕様（旧Swagger仕様）のようなAPI記述形式の広範な採用において最も顕著です。OpenAPI仕様は、エンドユーザーがコードベースに実装することなく対話できる、美しくインタラクティブなAPIドキュメントを生成するための基盤を提供します。この自動生成されたドキュメントは、開発チームがカスタマイズおよび構築して、APIの使用に関するより包括的なユーザーマニュアルを作成できる中心的なリソースです。
この電子書籍では、優れた開発者エクスペリエンスに関連する要素と、ドキュメントがどのように適合するかを検討します。APIドキュメントのベストプラクティスを紹介し、Swaggerツールを使用してAPIのドキュメントを作成し、SwaggerHubで既存のドキュメントワークフローを改善する方法について説明します。
始めましょう！
API開発者エクスペリエンスの計画
成功するAPIは、会社のポートフォリオ内のファーストクラス製品と同じ注意と配慮をもって扱う必要があります。APIを扱う際に製品管理の原則を適用することは、APIをファーストクラス製品として扱うための最初のステップです。このセクションでは、API開発者エクスペリエンスを計画するための3つの重要なステップを紹介します。
- APIのターゲットオーディエンスを理解する
- API採用プロセスを理解する
- 適切なオーディエンスタイプへのプロセスのマッピング
APIのターゲットオーディエンスを理解する
前述のように、ドキュメントはAPIの使用方法マニュアルです。あらゆる製品と同様に（そして、APIは製品です）、最初にAPIのドキュメントを消費する必要がある人を理解する必要があります。以下の図は、APIドキュメントの潜在的なオーディエンスの概要を示しています。
APIのコンテンツとドキュメントの最も一般的な消費者には、APIを直接統合して使用する必要がある人々と、このAPIが開発およびビジネス戦略に適合するかどうかを評価したい人々が含まれます。これらは2つのグループに分類できます。
- **APIユーザー：**サービスと統合したい開発者であり、APIを使用して特定の問題を解決しようとしています。
- **API意思決定者：**サービスを評価し、戦略的なニーズを解決するかどうかを確認する人々です。
APIのオーディエンスを分類し始めると、提供する必要があるリソースの種類と、これらのリソースをどのように提示する必要があるかを理解しやすくなります。
API採用プロセスの理解
オーディエンスは、サービスに完全にコミットする前に、APIの発見と評価のさまざまな段階を経ることになります。このユーザーフローは、ターゲットオーディエンスを認識から、最終的にAPIサービスの使用に十分なほど慣れ親しむまで導きます。適切に設計されたAPIは、このプロセスのあらゆる段階で最適な開発者エクスペリエンスに対応します。
以下の図は、ユーザーがAPIを採用する前に経験する主要な段階の概要を示しています。これらの段階は、4つの主要な質問に簡素化できます。
- なぜそれを使用する必要があるのか？
- どのように登録するのか？
- どこから始めるのか？
- どのように使用するのか？
オーディエンスが重複する場合もありますが、ユーザーの旅を分類することで、APIの採用に関与するさまざまな人とどのようにコミュニケーションをとる必要があるかを理解するための出発点を確立できます。
これらのフェーズは、組織内のさまざまな役割にも関連しています。たとえば、最初の2つの段階は、製品マーケティングの演習に近いです。サービスの価値と、既存の見込み客の課題をどのように軽減するかを伝えることに重点が置かれています。もちろん、次の2つの段階は純粋に技術的な文書作成の演習であり、技術ライターはエンドユーザーがサービスを理解して統合できるようにコンテンツを作成する必要があります。
これらのさまざまな段階を詳しく見ていきましょう。
「なぜあなたのAPIを使用する必要があるのか？」
このフェーズの目的は、オーディエンスにサービスの概要を、達成したいタスクにすぐに共感できる方法で提供することです。APIユーザーと評価者は、APIが提供する価値と、APIの使用を開始する方法をすぐに理解する必要があります。これは、ターゲットオーディエンスが初めて提示された情報とやり取りする場所です。この情報をシンプルかつ効果的に提示するには、これらの見込み客がなぜAPIにアクセスしてくるのか、どのようにサービスを発見するのか、サービスによって解決できる既存の問題は何なのかを理解する必要があります。これをうまく行っている企業の例を2つ紹介します。
「どのように登録するのか？」
APIサービスがユーザーや意思決定者にとって価値があると納得してもらえれば、彼らは次のステップに進みます。登録プロセスはAPIサービスを利用するための最初のステップです。このプロセスはできるだけシンプルにするべきですが、ユーザーを効果的に管理するために必要な情報も取得できる必要があります。1つの戦略としては、TwitterやGitHubなどの一般的なサードパーティサービスを使用して開発者がサインアップできるようにすることです。これらのサービスを使用すると、多くのハードルを設けることなく、簡単に連絡先情報を取得できます。
APIへのアクセス登録に余分なステップを含める必要がある場合は、プロセスを加速するための包括的なドキュメントとヘルプヒントを提供してください。悪い開発者エクスペリエンスの一例として、ユーザーに長いフォームに入力させたり、APIキーを提供する前に不要な詳細を要求したりすることが挙げられます。
「どこから始めればいいのか？」「どうやって使うのか？」
ターゲットオーディエンスがAPIへのアクセス登録を終えたら、次のステップは彼らをスタートさせることです。
これらは、APIサービスの利用に向けた開発者ジャーニーの最終段階です。彼らはAPIコードを実際に試してみて、最終的には独自のアプリと統合したいと考えています。
彼らをこのジャーニーを通して導くための秘訣は？
優れたAPIドキュメントです。
ドキュメントは優れた開発者エクスペリエンスの中心です
簡潔で明確なドキュメント（APIコンシューマーがアプリケーションに迅速に採用できるようにする）は、APIの採用を促進したい組織にとってもはやオプションではありません。
以下の点を考慮してください
- SmartBearの2016年のAPIレポートによると、APIを開発する組織の75％が正式なドキュメントプロセスを備えています。46％は、それが組織にとって最優先事項であると述べています。
- ProgrammableWebによる調査では、APIコンシューマーは、価格やAPIのパフォーマンスよりも、完全で正確なドキュメントをAPIの意思決定に影響を与える最大の要因と考えていました。
優れたドキュメントは開発と利用を促進し、サポート対応に費やされる時間と費用を削減します。内部APIユーザーにとってもドキュメントが重要であることを忘れないでください。内部関係者がAPIの使用方法を熟知していると仮定しないでください。
APIドキュメントには何が含まれるべきでしょうか？APIを文書化する際に役立つヒントをいくつかご紹介します。
ヒント＃1：基本事項をリストする
優れたAPIドキュメントには必ず含まれるべきセクションがいくつかあります。これらのセクションがないと、コンシューマーはAPIの使用方法を理解するのが困難になります。
- 認証。これは、ユーザーがAPIの利用を開始するために必要な認証スキームに関する情報です。たとえば、OAuthを使用している場合は、OAuthアプリケーションの設定方法とAPIキーの安全な取得方法を説明することを忘れないでください。
- エラーメッセージ。エラーメッセージは重要です。なぜなら、APIサービスと誤った方法で統合した場合にフィードバックを得たいからです。エラー基準を説明し、エンドコンシューマーがエラーが発生した場合の対処方法も提供してください。
- エンドポイントとそれらを消費する方法に関する情報。リクエストとレスポンスのサイクルの説明に注意してください。これらは、ユーザーがサービスとやり取りするAPIの主要なコンポーネントであるため、注意深く検討してください。
- 利用規約。これは、コンシューマーと組織間の法的合意であり、コンシューマーがサービスをどのように使用するべきかを定義しています。これは、開発者とコンシューマーが組織の推奨事項に従い、ビジネス価値に反するようなことをしないようにするために重要です。
- ベストプラクティスに従って、利用規約と共にAPIの制限を含めてください。制約も明確に記述する必要があります。そうすることで、コンシューマーはどのようなAPIの使用と実践が許可されているかを理解できます。
- 変更ログ。APIの更新とバージョン、そしてそれがAPIコンシューマーにどのように影響するかを詳細に説明します。これにより、コンシューマーはAPIの安定性を把握し、効果的なAPIコールを行うために変更が必要かどうかを確認できます。これらのセクションをリストアップしたら、APIはすでに順調なスタートを切っているので、それらを文書化するのは簡単です。
ヒント＃2：人間のために書く
ほとんどのAPIドキュメント作成者は、ドキュメントの対象読者が100％開発者である、つまりAPIの使用方法を完全に技術的に理解している人々であると仮定しています。しかし、APIを使用する多くの人が、使用しているドメインや専門用語を熟知していない可能性があることを覚えておいてください。ドキュメントは、通常は開発者であるAPIユーザーと、比較的技術に詳しくないAPI評価者（通常はプロダクトマネージャーやCTO）に対応する必要があります。
各呼び出しについて、英語のドメインの説明からドキュメントを作成してください。多くの技術的な専門用語を使用せず、APIを初めて使用する人でも簡単に理解できる方法で記述してください。
技術的な専門用語やドメイン固有の専門用語がある場合は、その特定の項目を、これらの用語を説明するさらに詳しいドキュメントにリンクしてください。これらの戦術により、パラメーター、ヘッダー、応答の詳細に迷う前に、API全体とその特定の呼び出しが存在する理由の明確さと適切な構造が確保されます。
StripeのAPIドキュメントのこの例を考えてみましょう。彼らは、使用している技術用語をすべて、それらを説明する追加のコンテンツでうまくサポートしています。
ヒント＃3：リクエストとレスポンスのサイクルを説明する
APIユーザーは、成功したAPI呼び出しから何が期待できるかを正確に知っておく必要があります。サポートされているすべての形式で、完全なサンプルレスポンス本文を記述します。XMLやJSONのような形式だけでなく、HTTPヘッダー、エラーコード、メッセージについても考えてください。エンドコンシューマーにとって情報が多すぎることは問題にはなりません。特に、サービスをアプリケーションに統合しようとしている場合。
APIが返すはずのすべてのオブジェクトの例、およびユーザーがAPI呼び出しを成功させるために追加できるパラメーターの例を提供します。これはStripeの別の例です。エンドユーザーは、ドキュメントの冒頭で各エラーコードの意味を簡単に理解できます。
ヒント＃4：実験は力なり
基本的なドキュメント以外にも、チームがエンドコンシューマーに提供するエクスペリエンスを強化するために提供する追加のリソースがあります。
- 入門ガイド：「入門」ガイドは、APIの実装を決定した開発者にとって役立つ次のステップのリソースになる可能性があります。このリソースは、APIを迅速に消費する方法の詳細な手順を提供する必要があります。
- インタラクティブなドキュメントとコンソール：オーディエンスは、APIをアプリケーションに直接統合する前に、APIを試したいと考えています。サンドボックスまたはコンソールを提供して、開発者がソースコードを操作することなく、さまざまなエンドポイントのレスポンスを簡単にデプロイおよびリセットできるようにします。
- SDK：APIが公開されたら、エンドユーザーがAPIを効果的に消費できるようにするクライアントライブラリの構築に投資することをお勧めします。多くの開発者がサービスの価値を見出している場合、SDKを構築してくれるかもしれません。優れた開発者エクスペリエンスを提供することは、開発者コミュニティを育む優れた方法です。
- チュートリアル：サンプルスニペット、サンプルSDK、および優れたユースケースを提供して、ユーザーがサービスを理解できるようにします。
OpenAPIを使用したAPIドキュメント
現在、世界中の何千ものAPIチームがOpenAPI Specification (OAS)とSwaggerツールを使用して、社内および公開向けAPIのドキュメントを生成しています。
OpenAPI仕様の概要
OpenAPI仕様は、APIのコンタクトを定義する、人間と機械が読み取ることができる記述形式です。この契約は、リソースとサービスによって公開されるデータ、およびクライアントがこれらのリソースを呼び出す方法を定義します。この考え方はシンプルに見えますが、サービスが多くの言語で構築され、さまざまなデバイスのクライアントによって消費されるマルチプラットフォームAPIエコノミーでは、強力な影響を与えます。
SmartBear Softwareが2015年にこの仕様を寄付したとき、Swagger SpecificationからOpenAPI Specificationに名前が変更されました。REST APIの設計とドキュメント作成の業界標準となっています。APIワークフローにOASを実装することで、多くの実際的な用途があります。APIチームにとってOASの最も一般的な用途は、APIのエンドユーザーと簡単に共有できる美しいインタラクティブなドキュメントを生成することです。
OASは、APIドキュメントの処理においてチームが直面する2つの最大の課題に対処します。
1. APIドキュメントのメンテナンス
開発チームとエンドコンシューマーがAPIを効率的に使用できるように、ドキュメントのメンテナンスと更新は、困難で面倒なプロセスになる可能性があります。これは、静的なドキュメント（.PDFなど）を使用してエンドコンシューマーにドキュメントを提供する場合に特に当てはまります。OASを使用すると、APIの契約を定義し、Swagger UIやSwaggerHubなどのツールを使用してAPIのインタラクティブなUIを自動生成できます。
そのインタラクティブなUIは、チームがAPIドキュメントをさまざまな例、説明、エラーメッセージ、優れたAPIドキュメントに含まれるその他の詳細を使用して構築するためのキャンバスとして機能します。
2. 複数のサービスの相互作用
APIには、さまざまなサービス間の消費と相互作用のための共通インターフェースが必要です。テキストドキュメントやJavadocのような従来のAPIインターフェースでは、異なる言語のサービス間の相互作用は許可されません。
OASで定義されたWebサービスは、言語に依存せず、機械可読であるため、構築された言語に関係なく相互に通信できます。
OASを使用したAPIの文書化
OASを使用したAPIの文書化は、まず初期のOAS契約、つまり「仕様」を生成することから始まります。これは、APIの設計とドキュメントの基礎となります。以下は、その契約の例です。
openapi: 3.0.0
info
title: サンプルAPI
description: [CommonMark](http://commonmark.org/help/)またはHTMLによるオプションの複数行または単一行の説明。
version: 0.1.9
servers
- url: http://api.example.com/v1
description: オプションのサーバーの説明、例：メイン（本番）サーバー
- url: http://staging-api.example.com
description: オプションのサーバーの説明、例：テスト用の内部ステージングサーバー
paths
/users
get
概要: ユーザーの一覧を返します。
説明: CommonMarkまたはHTMLによるオプションの拡張説明。
レスポンス
'200': # ステータスコード
説明: ユーザー名のJSON配列
コンテンツ
application/json
スキーマ
型: 配列
要素
型: 文字列
APIのOASを生成するには、2つのアプローチがあります。
- 設計ファースト: まずOpenAPI仕様を策定し、OpenAPI定義などの人間と機械が読み取れる契約に変換します。それからコードを構築し、ドキュメントを生成します。
- コードファースト: ビジネスプランに基づいて、APIを直接コーディングします。それからOpenAPI定義などの、人間または機械が読み取れるドキュメントを生成し、ドキュメントを作成します。
どちらのアプローチにも利点と欠点があり、最終的には、APIで解決したい、あなたの喫緊の技術的および戦略的ニーズに最適なアプローチを選択することになります。
設計ファーストアプローチは台頭し、採用が増えていますが、現在も多くの組織がコードファーストアプローチを採用しています。ドキュメントがエンドユーザーにとって重要であることを認識しているこれらの組織は、既存のAPIからOpenAPI定義を生成するためにサードパーティツールを使用し、そのOpenAPI定義を使用して、オープンソースのSwagger UIやSwaggerHubなどのツールを活用してインタラクティブなAPIドキュメントを生成します。
このプロセスを効率化するために、Swaggerチームは最近、OAS定義を生成するための新しいツールであるSwagger Inspectorをリリースしました。Swagger Inspectorは、APIリクエストを迅速に実行し、レスポンスを検証し、対応するOpenAPI定義を生成するための使いやすい開発者ツールです。
最新のSwaggerツールの一つであるSwagger Inspectorを使用して、コードファーストアプローチを実際に行動に移してみましょう。
Swagger InspectorによるOpenAPI定義の生成
Swagger Inspectorを使用して、各エンドポイントを呼び出し、関連するレスポンスを選択してOAS準拠のドキュメントを生成するか、一連の呼び出しをまとめて複数のAPIエンドポイントの完全なOASドキュメントを生成することにより、既存のREST APIのOASベースのドキュメントを迅速に生成します。
チームがSwaggerにどのようなアプローチをとるかに関係なく、APIのドキュメントを作成するために必要な作業があります。ほとんどの場合、組織は技術ライターにドキュメントの作成を依頼します。これには、エンドユーザーがAPIを成功させるために使用できる、意味のある、分かりやすい情報を追加することが含まれます。この契約から、Swagger UIを使用してドキュメントのインタラクティブなバージョンを生成できます。Swagger UIを使用すると、開発チームでもエンドユーザーでも、実装ロジックを何も配置することなく、APIのリソースを視覚化して操作できます。
Swagger Inspectorアカウントを使用すると、呼び出したエンドポイントのOpenAPIファイルを自動的に生成して、開発時間を節約することもできます。Swagger Inspectorは、チーム向けのAPI設計およびドキュメントプラットフォームであるSwaggerHubと緊密に統合されています。この統合により、開発者はAPIドキュメントをSwaggerHubに自動的にホストして視覚化し、社内および社外の利害関係者によるAPIの検出と利用を可能にします。
開始するには、以下の手順に従ってください。
既存のAPIからOpenAPIを生成する方法
Swagger Inspectorにアクセスし、ドキュメント化したいリソースのエンドポイントをリクエストします。次に、Swagger Inspectorの右側のセクションにある[履歴]パネルに移動し、[API定義の作成]をクリックしてOAS定義を作成します。
Swagger Inspectorの優れた点は、コレクション機能です。複数のエンドポイントを選択し、コレクションを通じてそれらのドキュメントを1つのOpenAPIファイルに統合します。
すでにSwaggerHubアカウントをお持ちの場合は、それらの資格情報を使用してSwagger Inspectorにログインできます。
生成された定義は、チームがAPIドキュメントを作成するためのOAS準拠の構造を提供します。定義が整ったら、サポートされているコンテンツタイプ、説明、例、認証タイプなど、重要な詳細を追加できます。
次に、SwaggerHubでこの定義からAPIドキュメントの作成を継続する方法について詳しく説明します。
SwaggerHubによる拡張APIドキュメント
前述のように、APIドキュメントの作成は容易ではありません。組織は、技術文書の作成だけでなく、ドキュメントが安全で使いやすくあることを確認する必要があります。ホスティングやメンテナンスなどの運用上の考慮事項があり、これらは組織に金銭的および時間的な追加オーバーヘッドがかかります。
そのため、SwaggerHubのような専用の組織プラットフォームが役立ちます。SwaggerHubは、チームがAPI開発ワークフロー全体で一貫性と規律を促進するために構築された、統合されたAPI設計およびドキュメントプラットフォームです。
SwaggerHubのインタラクティブなドキュメントは、OAS定義を視覚的にレンダリングしてライブでのインタラクションと操作性を提供するため、エンドユーザーはコードベースに統合する前に、APIがどのように読み込まれ、動作するかを正確に知ることができます。
これは、SwaggerHubエディターを使用してゼロから作成するか、ファイルシステムやソースコード管理ホストからインポートできるAPI契約から直接生成されます。
SwaggerHubで始めるにはいくつかのオプションがあります。前述のように、Swagger Inspectorを使用してOAS定義を生成し、SwaggerHubにインポートできます。
新しいAPIプロジェクトを開始する場合は、SwaggerHubエディターを使用すると、新しいAPIの設計を簡単に開始できます。チームの開始に役立つ機能の一部を見てみましょう。
リアルタイムのビジュアルレンダリング
SwaggerHubは、APIのすべてのエンドポイントをOASで定義するための強力なビジュアルエディターを提供するため、APIアーキテクトと開発者は、コードを記述する前に、コンシューマーがAPIとどのようにやり取りするかを理解できます。SwaggerHubは、ドキュメントをAPIワークフローの中心に置き、APIの契約に加えた変更ごとに更新されるインタラクティブなUIを自動生成します。
安全な自動ホスティング
SwaggerHubを使用すると、APIのドキュメントをホストするためのバックエンドサーバーを設定する必要がなくなります。SwaggerHubを使用すると、ドキュメントを1つの集中型プラットフォームにホストし、APIの開発チームまたはエンドユーザーに制御されたアクセスを簡単に提供できます。SwaggerHub内からドキュメントを公開したり、非公開にして社内チームメンバーやパートナーを招待して安全に共有したりできます。
最適化され、混乱のないワークフロー
APIの設計とドキュメントには複数の利害関係者が関与しており、APIを正常にリリースするには、優れたコラボレーションが不可欠です。主要なAPIワークフローに追加される更新を厳密に制御することで、より効果的に連携できます。共同作業者は、フォークしてメインAPIのコピーを作成し、変更を追加し、視覚的な比較とマージ機能を通じて変更をメインAPIワークフローにマージできます。APIが変更されると、チームはすぐにメール通知を受け取ります。
ブートストラップされたAPI開発者ポータル
APIの開発者ポータルは、優れた開発者エクスペリエンスの自然な拡張であり、エンドユーザーがAPIを理解して使用できるようにするためのドキュメントとコードスニペットが含まれています。SwaggerHubの内蔵HTMLポータルジェネレーターを使用して、開発者ポータルの基盤となるクライアント側のコードを生成できます。ワンクリックで、SwaggerHubはHTMLテンプレートと、APIのドキュメントと開発者ポータル用の6つのクライアントSDK使用例を生成するため、開発チームがカスタマイズ、インタラクション、作業を非常に簡単に実行できます。
維持と反復
組織は、すべてのAPIドキュメントと関連するバージョンを一元的に管理できます。SwaggerHubのバージョン管理システムを使用して、既存のAPIドキュメントを段階的に構築するか、運用環境にあるAPIの複数のバージョンのドキュメントを維持します。既存のバージョンに基づいて安定した動作中のAPIのドキュメントを公開し、古いバージョンを段階的に廃止します。
優れたAPIドキュメントによる開発者エクスペリエンスの向上
ドキュメントはAPIの使用マニュアルであり、APIのビジネス目標の達成に大きく貢献するものであることを忘れないでください。OpenAPI仕様とSwaggerツールは、ドキュメントに関する懸念事項を軽減し、自動生成され、最小限のメンテナンスで済む、インタラクティブで人間と機械が読み取れるドキュメントを作成します。
コンシューマーが気に入るAPIドキュメントの作成には労力が必要ですが、その投資は、優れた開発者エクスペリエンス、容易な実装、APIの採用率の向上という形で大きな成果をもたらします。
SwaggerHubは、インフラストラクチャに関する考慮事項とセキュリティの実装をすべて排除するため、組織はシームレスに協力して、コンシューマーと開発チームが気に入る優れたAPIドキュメントを作成できます。
15万以上のAPI開発者と組織が、SwaggerHubを信頼してAPIドキュメントのワークフローを改善しています。
SwaggerHubがどのようにチームを支援できるかを確認してください。今すぐ無料で開始してください。