API設計ツール「Swagger Editor」の使い方と特徴を解説

「APIのドキュメントを書くならSwagger Editorが便利」と聞いたことがあるものの、

・Swagger Editorの基本的な使い方がよく分からない…。
・他のAPI設計ツールとの違いや連携方法が知りたい…。

と悩んでいる方は多いのではないでしょうか。そこでこの記事では、

・Swagger Editorの特徴や基本的な概要
・導入方法や操作手順

について、初めてAPI設計を担当する方でもわかりやすく解説します。

Swagger Editorとは？

Swagger Editor（スワッガー エディター）はOpenAPIを基盤とし、YAMLまたはJSONフォーマットでAPIを設計できるエディタ型ツールです。

出典：Swagger Editor

記述内容は即座にプレビューされ、構文ミスがあればその場で検出されます。これにより、設計ミスを早期に発見し、スムーズに修正できます。

操作も直感的で、構文エラーがあれば即座に警告が表示されるため、ミスを最小限化することが可能です。インストールせずとも利用する方法もあり、API設計を担当するエンジニアにとって欠かせないツールといえるでしょう。

APIについて詳しくは「Web開発に役立つAPI連携とは？利用するメリットや実装手順を紹介」をご覧ください。

SwaggerとOpenAPIの違い

Swaggerはもともと、OpenAPI 2.0（かつてのSwagger spec）対応のAPI定義とドキュメント生成を目的に開発され、現在は複数のツールを含むブランド名として使われています。

一方、OpenAPIはAPI仕様を標準化したフォーマットであり、RESTful APIの設計図をYAMLやJSONで記述するための業界標準仕様です。現在はOpenAPI 3.xが主流となり、Swaggerツールもこの最新仕様に対応し進化しています。

RESTful APIについて詳しくは「RESTful APIとは？RESTの6原則とメリット・デメリットを解説！」をご覧ください。

　

Swaggerの主な機能をそれぞれ紹介

前述のとおり、SwaggerはSwagger Editorを含むツール群であり、主要な機能としては次の通りです。

• Swagger Editor：APIの仕様書を書くためのエディタ
• Swagger UI：ブラウザ上でAPIの動作を確認する
• Swagger Codegen：プログラミングのコードを自動生成する
• Swagger Hub：API管理をチームで行う際に役立つ

　

Swagger Editor：APIの仕様書を書くためのエディタ

Swagger Editorは、OpenAPI仕様に基づいたAPI定義を、YAMLまたはJSON形式で記述・編集できるブラウザベースのエディタです。リアルタイムプレビューに対応し、構文エラーも即時検出されます。

オンライン版とローカル版が利用でき、オンライン版はインストール不要、ローカル版はDockerやGitHub経由で導入できます。詳しくは後述の「ローカル版の環境構築1：GitHubからクローン」で解説するため、気になる方はそちらをご確認ください。

Swagger UI：ブラウザ上でAPIの動作を確認する

Swagger UIは、OpenAPI定義をビジュアル化し、ブラウザ内でAPIのレスポンスも手軽に確認できるツールです。画面上でAPI仕様が見やすく表示され、エンドポイントごとの詳細も簡単に確認できます。

さらに、ブラウザ上から実際のレスポンスを検証可能なため、非開発者でも理解しやすいインターフェースです。

Swagger Codegen：プログラミングのコードを自動生成する

Swagger Codegenを使えば、OpenAPI定義を基にクライアントまたはサーバー用のコードを各言語向けに自動生成でき、開発工数が削減されます。これにより、開発者は設計から実装へスムーズに移行できます。

Swagger Hub：API管理をチームで行う際に役立つ

Swagger Hubは、チームでのAPI設計やレビュー、バージョン管理を支援するクラウドサービスです。

Swagger EditorやUIと統合されており、CI/CDとの連携も可能なため、APIの自動テストやデプロイをワークフローに組み込むことができます。

　

Swagger Editorの使い方

Swagger Editorは、オンライン・ローカルのどちらでも利用可能です。

オンライン版はインストール無しで利用が可能で、ローカル版は「GitHubからクローンして利用する方法」と「Dockerを利用する方法」の2種類に分けられます。利用目的に応じて適切な方法を選ぶことで、効率的にAPI設計を進められます。

ここでは、オンライン版のアクセス方法と、ローカル版の環境構築を紹介します。

• オンライン版のアクセス方法
• ローカル版の環境構築1：GitHubからクローン
• ローカル版の環境構築2：Docker
• 基本的な操作手順

　

オンライン版のアクセス方法

オンライン版は、インストールなどの環境構築の手間がかかりません。公式サイトにアクセスして「Try Swagger Editor」から起動できます。

基本的な動作の確認はできますが、書いた文章をYAML/JSON形式で出力することはできないため注意が必要です。

「YAML/JSON形式で出力したい」「機密情報が含まれるのでローカル環境を作りたい」という方は、次の方法で環境構築を進めましょう。

ローカル版の環境構築1：GitHubからクローン

今回は、Windows 11の環境で実施しており、次の3つがインストールされていることが前提条件です。

・git（バージョンは不問）
・Node.js（20.3.0以上）
・npm（9.6.7以上）

GitHubについて詳しくは、「GitHubとは？特徴からアカウント登録方法まで徹底解説！」をご覧ください。

作業用のディレクトリを作成し、コマンドプロンプトを起動して次のコマンドを実行します。

カレントディレクトリ内に「swagger-editor」ディレクトリが作成されるため、次のコマンドを実行します。

このとき、次のようなエラーが出力される場合があります。これは、インストールするパッケージの依存関係に関するエラーです。

それぞれの依存関係を修正して再度実行するか、次のコマンドでインストールを進めてください。

インストールができたら、次のコマンドで起動します。

ブラウザを開き「localhost:3001」でアクセスすると、画面が立ち上がります。

オンライン版と異なり、ローカル版では「Save as YAML」や「Convert and save as JSON」が選べます。

ローカル版の環境構築2：Docker

検証環境はWindows 11でDocker Desktopがインストールされている環境です。基本的な流れは、Docker Hubからイメージをpullし、コンテナを起動する、という流れとなります。「Dockerがわからない」という方は、「Dockerとは何かを入門者向けに解説！基本コマンドも」もご確認ください。

コマンドプロンプトを立ち上げ、次のコマンドを実行します。

Docker Desktopを見ると、イメージが正常にpullできていることがわかります。

再びコマンドプロンプトに戻り、次のコマンドを実行してコンテナを立ち上げます。

Docker Desktopでも、コンテナが立ち上がっていることを確認できます。

ブラウザを立ち上げ「localhost」にアクセスすると画面が立ち上がります。

基本的な操作手順

新規に作成する際は「File」→「Clear editor」を選択するとゼロクリアできます。

以下は、基本的な構造で記述した例です。OpenAPI定義の基本構造は次の3つで構成されています。

・メタデータ：openapi,infoの部分。OpenAPIのバージョン、API情報などを記載
・サーバー：serversの部分。APIサーバーとそのURLなどを記載する。サーバーは複数定義可能
・パス：pathsの部分。APIのパス、サポートされるHTTPメソッドを定義

左ペインにYAMLまたはJSON形式でAPI仕様を記載していくと、右ペインにリアルタイムで反映され、UI形式のプレビューが表示されます。この時、バリデーションエラーがあればその旨も表示されるため、随時対応できるようになっています。

作成した仕様は「File」→「Save as YAML」または「Convert and save as JSON」でエクスポートできます。

YAML形式の場合は「openapi.yaml」、JSON形式の場合は「openapi.json」として出力されます。

　

Swagger EditorによるAPI設計方法

API仕様の中心となる「paths」の内容について、もう少し掘り下げて解説します。

• GET/POSTなどのCRUD操作を設計する
• schemasでデータモデルを定義する
• securitySchemesでセキュリティを設定する

　

GET/POSTなどのCRUD操作を設計する

CRUD操作を設計する際は、まずpathsセクションでエンドポイントとHTTPメソッドを定義します。例えば、/usersエンドポイントにgetメソッドを追加し、ユーザーリスト取得機能を設計できます。

リクエストボディはrequestBody、レスポンスはresponsesで詳細を記述し、データ構造をschemasで記述することで、明確な仕様が完成します。

schemasでデータモデルを定義する

OpenAPIのcomponents.schemasセクションを使えば、APIで使用するデータモデルを一元管理できます。YAML形式で構造を記述し、各エンドポイントでは「$ref」を使って参照することで、定義の重複を避けつつ記述の一貫性を保てます。

また、type（例：stringやinteger）、required（必須項目の指定）、format（例：email、date-timeなど）といった属性を使うことで、より厳密なデータ検証が可能です。これにより、APIの信頼性と可読性が向上します。

securitySchemesでセキュリティを設定する

APIの認証方法は、components.securitySchemesで一元定義できます。APIキー認証、Bearerトークン認証、OAuth2認証をYAML形式で記述し、securityプロパティで適用の有無を設定可能です。

認証定義は複数のエンドポイントで再利用可能なため、管理がしやすいです。例えば、一般ユーザー向けAPIにはAPIキーを、管理者専用エンドポイントにはOAuth2を適用する、といった柔軟な運用が可能です。

　

Swagger Editorを利用するメリット

最後に、Swagger Editorを利用するメリットを簡単にまとめて解説します。

リアルタイムプレビューで即時に確認が可能

編集画面がリアルタイムでUIに反映されるため、入力ミスや仕様の矛盾を即座に把握できます。画面が左右に分かれており、視認性も高く、作業効率が上がります。

構文エラーの自動検出が可能

YAMLの書式ミスや誤字は編集画面で即指摘されるので、修正もスムーズです。正確な仕様書を効率よく作成できます。

OpenAPI仕様に準拠した設計が可能

最新のOpenAPI 3.0/3.1仕様に対応しており、業界基準に沿った設計が可能です。互換性のあるドキュメントは、外部システムとの連携も円滑になります。

Swaggerツールとの親和性が高い

Swagger UIやCodegen、Hubと連携することで、定義ファイルからドキュメント生成・コード生成・レビュー管理まで一貫して対応できます。チーム開発の効率が大きく向上します。

クラウドでもローカルでも使用可能

オンライン版はインストール不要で手軽に利用でき、ローカル版はオフライン作業や機密情報の取り扱いに適しています。用途に応じて柔軟に使い分けられます。

　

Swagger Editorを使って簡単にAPI設計をはじめよう！

Swagger Editorは、初心者でも直感的に扱えるAPI設計ツールです。リアルタイムプレビューや構文チェック、他ツールとの連携など、多くの利便性を備えています。個人開発からチームプロジェクトまで幅広く活用でき、API設計の標準化・効率化に貢献します。

さらに詳しく学びたい方には、Swagger Editorの実践を含むUdemy講座がおすすめです。API設計・ドキュメント作成・テストまで体系的に学べる構成で、スマートフォンからも視聴可能です。

◆「OpenAPI (Swagger)入門：API設計手法を学ぼう！Swaggerの概念からAPIドキュメントの書き方まで」

レビューの一部をご紹介

評価：★★★★★
コメント：しっかり学んでいけそうです

Swagger EditorでAPI設計のスキルを向上させましょう！