Stoplight Studioとは？OpenAPI設計とドキュメンテーションツールのおすすめ

Stoplight Studioは、API設計・ドキュメント作成・公開のためのツールですが、業界で最も有名なOpenAPIドキュメンテーションツールとして認識しても良いと思います。それでは、本文では、このStoplight StudioがAPIドキュメンテーションにおいての強みを消化した上、非常に使いやすいOpenAPI設計とドキュメンテーションツールを皆さんに紹介しようと思います。

Stoplight Studioとは

Stoplight Studioは、API設計・ドキュメント作成・公開のためのツールです。

主な特徴は以下の通りです。

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

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

Stoplight StudioとOpenAPI

Stoplightは2022年5月にSwaggerの開発元であるSmartBear Softwareによって買収されています。買収の背景としては、以下の点があげられています。

• SwaggerとStoplightはともにAPIライフサイクル管理に強みを持つため、両製品の特徴を生かすことができる
• StoplightにはAPIテストやマイクロサービス対応などSwaggerよりも先進的な機能がある
• SmartBear側としてはAPIManagement分野でのプレゼンスを高められる

買収後は、SwaggerとStoplightの製品を統合していく方針のようです。 例えば、Stoplightの機能をSwaggerHubに追加していくといった形です。また、過去はSwagger Specificationと呼ばれる独自仕様がSwaggerツールで使われていました。しかし、2015年にSwagger SpecificationをベースにOpenAPI Initiativeが結成され、OpenAPI仕様が制定されました。

ということで、OpenAPI仕様は、Swagger Specificationをベースにして開発してきたものになりますので、Swaggerの開発元に買収されたStoplight Studioも、OpenAPI標準の設計やドキュメンテーションツールを目指していると言えるのでしょう。

Stoplight Studioの強みと弱み

Stoplight Studioは、業界で最も優れているAPIドキュメンテーションツールとして認識されています。この部分では、Stoplight Studioの強みと弱みをまとめて皆さんに紹介していきたいと思います。

Stoplight Studioの強み

従来のAPIドキュメンテーションツールとは異なり、Stoplight Studioは、JSON/YAMLを記述してAPIを設計するのではなく、非常にインタラクティブなビジュアルエディタを提供していますので、ユーザーが直感的なUIでAPIを定義したり、設計したりすることができるようになります。また、APIの設計が終わった後、直ちに読みやすいAPIドキュメントを生成したり、インターネット上に公開したりすることができます。

従来のテキストベースの記述と比べると、Stoplight Studioの直感的な操作性が大きなメリットだと思います。

Stoplight Studioの弱み

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

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

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

オールインワンのAPIドキュメンテーションツール - Apidog

それでは、Stoplight Studioの他に、どのようなツールを利用してAPIを設計したり、APIドキュメンテーションを作成したりすることができますか？それはApidogです。

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

また、オールインワンのAPIドキュメンテーションツールとして、ApidogはStoplight Stuidoの欠点を全面的に補足しています。ApidogはAPI設計やドキュメンテーション機能の他に、APIの単体テスト、シナリオテスト、パフォーマンステストなどにも対応できます。また、APIサーバーサイドができていない場合でも、Apidogのモックサーバーを利用してテストプロセスを前に進めることができるので、API開発のライフサイクル全体のプロセスを支援してくれるオールインワンのツールになります。

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 Studioは業界で最も優れたAPIドキュメンテーションツールとして知られています。インタラクティブなビジュアルエディタを備え、直感的な操作でAPI設計からドキュメント作成、公開までを実現できる点が大きな強みです。一方で、動的言語への対応不足やテスト機能の欠如などの短所も指摘されています。

そうした短所を補完するのが、オールインワンのAPIドキュメンテーションツールApidogです。Apidogも直感的なUIを備えつつ、APIの設計・ドキュメント作成に加え、テストやモックサーバー機能まで含む全ライフサイクルをサポートしています。具体的には、Apidogを使えばインタラクティブにAPI定義を行い、わかりやすいドキュメントを生成、共有することができます。APIの設計から公開まで、一貫したプロセスを効率的に遂行できる点が最大のメリットといえます。

したがって、API設計とドキュメンテーション作成に最適なツールを選ぶなら、Stoplight Studioの欠点を克服しつつ操作性を維持しているApidogが最良の選択肢であると評価できるのでしょう。