今日、あらゆる業界の組織が、APIプログラムへの投資がもたらすビジネス上および戦略上の機会を認識しています。APIはデジタルトランスフォーメーションを可能にし、エンジニアリングとビジネスの可能性を広げます。
しかし、APIエコノミーの成長は、APIを構築するチームにとって新しい考え方を必要とします。エンドユーザーがAPIを利用する価値を理解せず、利用を開始するために必要なリソースが利用できなければ、最高のAPIプログラムでも失敗に終わるでしょう。単にAPIが存在するだけでは不十分であり、優れたAPI開発者体験も必要です。
API開発者体験とは？
API開発者体験は、一般的なユーザー体験（UX）の延長線上にあります。これは、開発者がAPIとやり取りする際に経験するすべての総体です。優れたAPI開発者体験は、技術的な記述を超えたものです。これは、エンドユーザーがAPIを理解し、うまく連携するために必要なすべての適切なリソースを提供することです。
なぜAPI開発者体験が重要なのか？
今日の現代のソフトウェアの世界では、平均的な技術的消費者は、組織が実装することを決定するツールやプラットフォームに関して、計り知れないほどの購買影響力を持っています。Forresterの主席アナリストであるジェフリー・ハモンド氏によると、ソフトウェアチーム内での導入パターンは開発者へとシフトしており、開発者にはソリューションの導入を妨げたり助けたりする力が与えられています。
これは、ソフトウェア製品の技術的な採用者が、今や製品の採用と購入の意思決定者となっていることを意味します。したがって、今日のハイパーコネクトされた競争の激しいエコシステム、特にAPIエコノミーにおいては、技術的な採用者が製品を容易に利用できるようにすることが非常に重要です。
優れたAPI開発者体験の秘訣
優れた開発者体験を提供することに関して、高性能で使いやすいAPIに勝るものはありません。開発者体験は常に、チームが協力したいと考える信頼できるAPIを提供し、安全に統合できるという信頼を与えることから始まります。
優れた開発者体験を提供するための重要な要素は、正確で最新のAPIドキュメントを提供することです。APIドキュメントは、APIを正常に利用し、統合するために必要な情報です。これは、技術的な記述、コードサンプル、APIの利用方法をよりよく理解するための例の形をとることができます。
今日、最も有名で広く採用されているAPIの背後にある企業は、APIの豊富な、人間にとって親しみやすいドキュメントに投資しています。Facebook、YouTube、Microsoft、PayPal、DropBoxなどの企業は、社内および公開APIを使用して技術的なオーケストレーションと戦略的成長を推進しており、API開発者体験の中心にドキュメントを置いています。
APIドキュメントの旅を始めるには？
ドキュメントを中心とした優れた開発者エクスペリエンスの提供は、APIチームにとってかつてないほどアクセスしやすくなりました。かつてチームはPDFや手動で更新されるウェブページのような静的な形式のドキュメントに頼らざるを得ませんでしたが、現在ではドキュメントワークフローを自動化し、APIの利用をスムーズで簡単なプロセスにするインタラクティブなAPIドキュメントを構築するためのソリューションがあります。
組織がAPIを文書化する方法には大きな変化がありました。これらの変化が最も顕著なのは、OpenAPI Specification（旧Swagger Specification）のようなAPI記述形式が広く採用されていることです。これにより、エンドユーザーがコードベースに実装することなく操作できる、美しくインタラクティブなAPIドキュメントを生成するための構成要素が提供されます。この自動生成されたドキュメントは、開発チームがカスタマイズし、APIと連携するためのより包括的なユーザーマニュアルを作成するための中心的なリソースとなります。
このEブックでは、優れた開発者エクスペリエンスを提供する上で考慮すべき要素と、ドキュメントがどのように組み込まれるかについて見ていきます。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にたどり着いたのか、どのようにあなたのサービスを発見したのか、そしてあなたのサービスが解決できる既存の問題は何かを理解する必要があります。この点で優れている企業の例を2つ挙げます。
「どうやって登録するのか？」
APIのユーザーと意思決定者に、あなたのサービスが彼らに価値があると納得させたら、彼らは旅を続けるでしょう。登録プロセスは、あなたのAPIサービスにアクセスするための最初のステップです。このプロセスは可能な限り簡単であるべきですが、これらのユーザーを効果的に管理するために必要な情報を取得できる必要もあります。一つの戦略は、開発者が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をアプリケーションに直接統合する前に試してみたいと思うでしょう。サンドボックスまたはコンソールを提供して、開発者がソースコードを操作することなく、さまざまなエンドポイントに対する応答を簡単にデプロイおよびリセットできるようにします。
- SDK: APIがリリースされたら、エンドユーザーがAPIを効果的に利用できるクライアントライブラリの構築に投資することをお勧めします。多くの開発者があなたのサービスに価値を見出している場合、彼らがあなたのためにSDKを構築することさえあるかもしれません。優れた開発者体験を提供することは、開発者コミュニティを育成するための素晴らしい方法です。
- チュートリアル：ユーザーがサービスを理解するのに役立つサンプルスニペット、サンプルSDK、および優れたユースケースを提供してください。
OpenAPIによるAPIドキュメント
今日、世界中の何千ものAPIチームが、内部および公開向けAPIのドキュメント生成に、OpenAPI Specification (OAS)およびSwaggerツールを利用しています。
OpenAPI仕様の概要
OpenAPI仕様は、APIの「契約」を定義する機械可読および人間可読の記述形式です。この契約は、リソースとサービスによって公開されるデータ、およびクライアントがこれらのリソースを呼び出す方法を定義します。このアイデアは単純に思えますが、多くの言語でサービスが構築され、さまざまなデバイスのクライアントによって利用されるマルチプラットフォームAPIエコノミーにおいて、強力な意味合いを持ちます。
SmartBear Softwareが2015年に仕様を寄贈した際、Swagger SpecificationからOpenAPI Specificationに名称が変更されました。これは、REST APIがどのように設計され、文書化されるかに関する業界標準となっています。APIワークフローにOASを実装することには多くの実用的な用途がありますが、APIチームにとってOASの最も一般的な適用方法は、APIのエンドユーザーと簡単に共有できる、美しくインタラクティブなドキュメントを生成することです。
OASは、APIドキュメントを手がけるチームが直面する最大の課題の2つに対処します。
APIドキュメントの維持管理
開発チームとエンドユーザーがAPIを効率的に利用できるように、ドキュメントを維持・更新するのは、困難で面倒なプロセスとなる場合があります。特に、PDFのような静的なドキュメントを使用してエンドユーザーにドキュメントを提供している場合は顕著です。OASを使用すると、APIの契約を定義し、Swagger UIやSwaggerHubのようなツールを使用して、そのAPIのインタラクティブなUIを自動生成できます。
そのインタラクティブなUIは、チームがAPIドキュメントを構築するためのキャンバスとして機能し、優れたAPIドキュメントに不可欠なさまざまな例、説明、エラーメッセージ、その他の詳細を追加できます。
2. 複数のサービス連携
APIは、異なるサービス間の利用と対話のための共通インターフェースを必要としていました。従来のAPIインターフェース、つまりテキストドキュメントやJavadocsのようなものは、異なる言語で構築されたサービス間の対話を許可しません。
OASで定義されたWebサービスは、言語非依存で機械可読であるため、構築された言語に関係なく互いに通信できます。
OASを使ったAPIの文書化
OASによるAPIのドキュメント作成は、APIの設計とドキュメントの基礎となる最初のOAS契約、つまり「仕様」を生成することから始まります。以下に、その契約の例を示します。
openapi: 3.0.0
info
title: Sample 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
summary: ユーザーのリストを返します。
description: CommonMarkまたはHTMLで記述された任意の拡張説明。
responses
'200': # ステータスコード
description: ユーザー名のJSON配列
content
application/json
schema
type: array
items
type: string
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を使用して、既存のREST APIのOASベースのドキュメントを迅速に生成するには、各エンドポイントを呼び出し、関連するレスポンスを選択してOAS準拠のドキュメントを生成するか、一連の呼び出しをまとめて複数の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の右側にある履歴パネルに移動し、「Create API definition」をクリックしてOAS定義を作成します。
Swagger Inspectorの素晴らしい点は、コレクション機能です。複数のエンドポイントを選択し、それらのドキュメントをコレクションを通じて単一のOpenAPIファイルに統合できます。
すでにSwaggerHubアカウントをお持ちの場合、その認証情報でSwagger Inspectorにログインできます。
生成された定義は、チームがAPIドキュメントを構築するためのOAS準拠の構造を提供します。定義が整ったら、サポートされているコンテンツタイプ、説明、例、認証タイプなどの重要な詳細を追加できます。
次に、SwaggerHubでこの定義からAPIドキュメントを構築し続ける方法について、詳しく説明します。
SwaggerHubでAPIドキュメントを強化する
上記で詳述したように、APIドキュメント作成は簡単な作業ではありません。組織は技術的な記述に取り組むだけでなく、ドキュメントが安全で扱いやすいものであることを確認する必要があります。ホスティングやメンテナンスなどの運用上の考慮事項もあり、これらすべてが金銭と時間の両面で組織に追加のオーバーヘッドコストをもたらします。
そのため、SwaggerHubのような専門的な組織プラットフォームが役立ちます。SwaggerHubは、API開発ワークフロー全体で一貫性と規律を推進するためにチーム向けに構築された、統合されたAPI設計およびドキュメントプラットフォームです。
SwaggerHubのインタラクティブなドキュメントは、OAS定義を視覚的に表示し、ライブでの操作性と実用性を提供します。これにより、エンドユーザーはコードベースに統合する前に、APIがどのように読み取られ、動作するかを正確に把握できます。
これは、SwaggerHub Editorを使用してゼロから作成したり、ファイルシステムやソース管理ホストからインポートしたりできるAPI契約から直接生成されます。
SwaggerHubを始めるためのオプションはいくつかあります。前述したように、Swagger Inspectorを利用してOAS定義を生成し、SwaggerHubにインポートできます。
新しいAPIプロジェクトを開始する場合、SwaggerHubエディターを使用すると、新しいAPIの設計を簡単に開始できます。チームが開始するのに役立ついくつかの機能を見てみましょう。
リアルタイムの視覚レンダリング
SwaggerHubは、OASでAPIの各エンドポイントを定義するための強力なビジュアルエディターを提供し、APIアーキテクトと開発者がコードを記述する前に、ユーザーがAPIとどのように対話するかを理解できるようにします。SwaggerHubは、APIのドキュメントを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の使用マニュアルであり、APIのビジネス目標達成における最大の原動力の1つであることを忘れないでください。OpenAPI仕様とSwaggerツールは、自動生成され、最小限のメンテナンスで済む、インタラクティブで人間にも機械にも読みやすいドキュメントを作成することで、ドキュメントに関する懸念を軽減します。
顧客に喜ばれるAPIドキュメントを作成するには努力が必要ですが、その投資は、優れた開発者体験、より簡単な実装、そしてAPIの採用の向上という形で大きな利益をもたらすでしょう。
SwaggerHubは、すべてのインフラストラクチャの考慮事項とセキュリティの実装を排除し、組織がシームレスに協力して、消費者と開発チームに愛される優れたAPIドキュメントを作成できるようにします。
15万人以上のAPI開発者と組織が、APIドキュメントワークフローの改善にSwaggerHubを信頼しています。
SwaggerHubがチームをどのように支援できるかをご覧ください。今すぐ無料で始めましょう。