ガイド：Stoplight Stuidoの使い方、API設計やドキュメンテーションを行う

Stoplight Studioは、API設計・ドキュメント作成・公開のためのツールとして、多くのユーザーはStoplight Studioを利用してAPIを設計したり、APIドキュメントを作成したりしています。本文では、Stoplight Studioの詳細の使い方を皆さんに紹介します。API設計やドキュメンテーションを行いたい場合は、本文の内容を参照して操作してください。

Stoplight Studioとは

Stoplight Studioは、API設計・ドキュメント作成・公開のためのツールです。業界で最も有名のAPI設計やドキュメンテーションツールとして、多くのユーザーに利用されています。Stoplight Studio主な特徴は以下の通り：

• APIの設計からドキュメント作成、公開まで一貫したワークフローを提供している
• インタラクティブなエディタでAPIを視覚的に設計できる
• OpenAPI仕様に基づいたAPI定義ができる
• 基礎的なAPI疎通確認機能を提供している
• チームでのコラボレーションに対応している

つまり、Stoplight Studioを使うことでAPIの設計からドキュメント生成やドキュメントの公開まで一貫したプロセスで効率よく進めることができます。APIの設計・ドキュメンテーションにおいて強力なツールといえます。

Stoplight Stuidoの使い方：APIを設計してドキュメントを作成

それでは、どのようにStoplight Studioを使ってAPIを設計してAPIドキュメントを作成しますか？この部分では、Stoplight Studioの使い方を皆さんに紹介します。

Stoplight Studioを利用する操作手順

ステップ⒈Stoplight Studioにサインアップ

Stoplight Studioの利用を開始するには、このサービスにサインアップする必要があります。Stoplight Studioの公式サイトにアクセスして、「Get Started for Free」ボタンをクリックします。

ステップ⒉プロジェクトを作成

Stoplight Studioに成功にサインアップすると、Stoplight Studioのダッシュボードにリダイレクトされます。ここで左上にある「＋」ボタンをクリックして、APIプロジェクトを新規に作成します。

ステップ⒊プロジェクト情報を設定して作成

ここでプロジェクト名などの情報を記入して、「Create API Project」ボタンをクリックして、プロジェクトを作成します。

ステップ⒋プロジェクト内でAPIドキュメントを作成

プロジェクトの画面で「API」を選択して、APIドキュメントを新規に作成します。

ステップ⒌APIの情報を設定して作成

ここでAPIの名前、バージョン、およびフォーマットを設定した上、「Create」ボタンをクリックします。ここで、OpenAPIのファイルやPostmanのデータからインポートすることも可能です。

ステップ⒍APIエンドポイントを定義

新規にAPIを作成すると、APIに含まれるAPIエンドポイントを定義したり、新しいエンドポイントを作成して設計したりすることができます。例えば、次のようにエンドポイントの概要を記述します。

ステップ⒎エンドポイントの詳細を定義

エンドポイントを定義する際、上部のタブから「一般情報」、「パラメータ」、「リクエストボディ」、「レスポンス定義」に切り替えることができます。必要に応じて異なるタブに切り替えて、各項目を定義する必要があります。

ステップ⒏APIドキュメントを公開

API及び各エンドポイントの設計が終わる場合、右上の「Share」ボタンからそれを他人に共有したり、左上の「Publish」ボタンからそれをインターネット上に公開したりすることができます。インターネット上に公開した後、次のようなオンラインで閲覧できるAPIドキュメントページが生成されます。

以上は、Stoplight Studioを使って、API及びその下の各エンドポイントを設計してAPIドキュメントを生成する手順になります。API仕様を設計して、API仕様書を生成することが必要となる場合は、Stoplight Studioが非常に適切なツールになるのでしょう。

Stoplight Studioの欠点

しかし、Stoplight Studioは決して完璧なツールではありません。Stoplight Studioは以下のようなデメリットがあるとよく指摘されています：

• 動的言語向けのコード生成テンプレートが少ない
• 高機能な分だけ操作の習得に少し時間がかかる
• 対応できる言語が少なく日本語に対応できていない
• クラウド提供なのでオフライン環境に対応していない
• ドキュメンテーション機能の一方、APIテスト機能はあまりない

以上のように、Stoplight StudioはAPI設計やドキュメンテーションのプロセス全般を強力にサポートする優れたツールだと評価できますが、テスト機能の欠如、言語サポートなどのデメリットがあることも否定できません。

Stoplight Studioより強力のAPI設計ツール：Apidog

Apidogは、Stoplight Studioと同じように直感的なUIを提供しています。このGUIを利用して、YAMLやJSONコードを全く書く必要がなく、直感的な操作でAPIを設計したり、APIドキュメントを作成したりすることができます。また、APIドキュメントを生成した後、直接にドキュメントをインターネットに公開（カスタムドメイン機能を使って、自分のサイトにアップロードすることも可能！）したり、他の人に共有したりすることも簡単です。

また、Apidogは、APIの単体テスト、シナリオテスト、パフォーマンステストなどにも対応できます。さらに、Apidogには、モックサーバーが内蔵され、それを配置なしで直接に利用できますので、非常に便利です。

ApidogでAPIを設計してドキュメンテーションを生成

Apidogを利用して、APIを設計する場合は、下記のステップを参照して、非常に直感的な操作によってOpenAPI仕様に従ってAPIを設計することができます。そして、APIの設計が完了した後、APIドキュメンテーションを生成して、インターネットに公開したり、他人に共有したりすることも簡単です。

1. APIのメソッドとエンドポイントの設定

API仕様書を書き始める前にAPIの設計が必要となります。例えば、APIが提供できる機能、使用シーン、使い方を頭に明確にし、このAPIが技術上でも、業務上でも、合理的で実現可能であることを確認します。

APIのエンドポイント（パス）は具体的なウェブページではなく、ユーザーがサービスを見つけられる場所です。例えば、ユーザーがここで商品名を入力して、素早く商品を探せます。

パスを設定した上、APIのメソッドを設定します。通用なAPIメソッドは：

GET（コンテンツを取得）

POST（コンテンツを新規追加）

PUT（既存コンテンツを変更）

DELETE（コンテンツを削除）です。

2. APIの詳細を説明

APIのパスを設定した上、APIの利用者にAPIに関するより多くの情報を伝える必要があります。これらの情報には、APIの名前、機能説明、Requestのパラメータ、ResponseのパラメータやResponse例などが含まれています。

その中で、RequestとResponseのパラメータを設定する場合、各パラメータのデータタイプ、必須項目ではないか、パラメータの説明などの情報を記入することもできます。

こで記入する情報が多けば多いほど、API利用者のユーザーエクスペリエンスが高くなります。

3. APIケースを設定

APIケースの設定は、API仕様書の作成に対して非常に重要なステップです。APIケースは、開発者が当該APIの使い方を理解し、よりよくデバッグするのを助けることができます。ケースの作成中にAPIの各パラメータの意味と役割を明確に説明し、呼び出しの成功例と失敗例を明確に定義する必要があります。

4. APIのエラーコードを設定

APIのエラーコードは、APIの特徴と機能に基づいて設定される必要があります。エラーコードは問題の原因を明確に示し、開発者がより早く診断し、問題を解決できる解決策とアドバイスを提供するべきです。API仕様書でよく設計されたエラーコードがあることは、APIの使いやすさと信頼性を高め、開発者は故障排除に要する時間を減らすことができます。以下は参考になるAPIエラーコードタイプです。

5. バージョンコントロール機能の適用

API機能の開発に伴って、APIの情報を修正したり、変更したりする可能性があります。例えば、パラメータを追加したり、削除したり、変更したり、返すレスポンスのフォーマットを変更したりすることがよくあります。API仕様書にバージョンのコントロール機能がない場合、これら新しい変更は開発者に迷惑をかけ、彼らの開発効率に悪影響を及ぼす可能性があります。

そこでバージョンのコントロール機能を導入する必要があります。そうすると、異なるバージョンのAPIの変更点を表示することができるので、開発者は需要に応じて異なるバージョンを選択できますし、各バージョンの違いと変更をいち早く把握することもできます。

6. API仕様書の生成と共有

上記の操作ガイドを参照して、APIを定義すると、Apidogの共有機能を使って、非常にわかりやすいAPI仕様書を生成したり、他人に共有したりする事ができます。

左側メニューから「共有」をクリックして、「新しい共有」を選択すると、次のような共有設定が表示されます。ここで、共有するAPIを選択して、必要に応じてセキュリティ設定や言語の設定を終えて、「保存」をクリックします。

そして、新しい共有項目が表示されます。「開く」をクリックすると、API仕様書がブラウザに表示されます。

まとめ

本文では、Stoplight Stuidoの使い方を詳しく皆さんに紹介しました。Stoplight Stuidoを使って、APIを設計してAPIドキュメントを作成する必要がある場合は、このガイドが役立つと思います。

また、Apidogも同様にAPI設計からドキュメント作成までをサポートしつつ、Stoplight Studioよりも高機能なAPI管理ソフトになります。Apidogを使うと直感的な操作でAPI仕様書を作成し、共有することができ非常に便利です。そこで、API設計やAPIドキュメンテーションのニーズがあるユーザーは、Apidogという便利なツールをもご検討ください。