はじめに
Web開発をしていると、「API」という言葉をよく耳にします。
APIを開発・利用するうえで欠かせないのが仕様書です。
「どのURLにアクセスすれば良いのか」「どんなデータを送れば良いのか」といった情報をまとめたものがAPI仕様書ですが、手書きで管理すると更新漏れやミスが発生しがちです。
そこで登場するのが Swagger（スワッガー） です。
この記事では、Swaggerの基本的な概念と、OpenAPI仕様との関係を中心に解説します。
Swaggerとは
Swaggerとは、RESTful APIの仕様を記述・管理・可視化するためのツール群です。
もともとはSmartBear社が開発したオープンソースプロジェクトで、現在は OpenAPI Specification（OAS） という標準仕様をベースにしています。
一言で表すと、「APIの設計書を書いて、そこからドキュメントや便利なツールを自動生成できる仕組み」です。
Swaggerで何ができるのか
Swaggerを使うと、主に以下のことができます。
- APIドキュメントの自動生成：YAMLまたはJSONで仕様を書くと、見やすいドキュメントが自動で生成される
- APIの動作確認：ブラウザ上からAPIにリクエストを送って動作確認ができる
- チーム間の認識合わせ：フロントエンドとバックエンドでAPI仕様を共有しやすくなる
OpenAPI仕様との関係
Swaggerを調べていると、OpenAPIという言葉もよく出てきます。この2つの関係を整理しておきましょう。
| 用語 | 説明 |
|---|---|
| OpenAPI Specification（OAS） | RESTful APIの仕様を記述するための標準仕様（フォーマットのルール） |
| Swagger | OpenAPI仕様に基づいてAPIを管理・可視化するためのツール群の総称 |
簡単に言うと、OpenAPIは「仕様（ルール）」、Swaggerは「そのルールに対応したツール」 という関係です。
歴史的な経緯
もともとSwaggerはツール名であると同時に、API仕様のフォーマット名でもありました。
2016年にそのフォーマット部分が OpenAPI Specification として独立し、Linux Foundationのもとで標準化されました。
そのため、古い記事では「Swagger仕様」と書かれていることもありますが、現在は OpenAPI仕様 と呼ぶのが正式です。
【まとめると】
Swagger仕様（旧称）＝ OpenAPI Specification（現在の正式名称）
Swaggerツール群 ＝ OpenAPI仕様に対応したツールセット
OpenAPI仕様ファイルの書き方（YAMLサンプル）
OpenAPI仕様はYAMLまたはJSONで記述します。ここではYAMLの例を紹介します。
openapi: 3.0.0
info:
title: サンプルAPI
version: 1.0.0
paths:
/users:
get:
summary: ユーザー一覧を取得する
responses:
'200':
description: 取得成功
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 山田太郎
各項目の解説
| 項目 | 説明 |
|---|---|
openapi |
使用するOpenAPI仕様のバージョン |
info |
APIの基本情報（タイトル、バージョンなど） |
paths |
APIのエンドポイントとその定義 |
responses |
レスポンスのステータスコードと内容 |
schema |
データの型や構造の定義 |
このYAMLファイルをSwagger UIに読み込ませると、自動的にドキュメントとして表示されます。
Swaggerの主なツール一覧
Swaggerにはいくつかのツールがあります。代表的なものを紹介します。
| ツール名 | 役割 |
|---|---|
| Swagger UI | OpenAPI仕様をブラウザ上でビジュアル表示する |
| Swagger Editor | ブラウザ上でYAML/JSONを書いてプレビューできるエディタ |
| Swagger Codegen | 仕様からサーバーやクライアントのコードを自動生成する |
まずはブラウザで使える Swagger Editor を触ってみるのが入門として最適です。デモ用のYAMLが最初から表示されており、その場で編集しながらプレビューを確認できます。
まとめ
この記事で紹介した内容を振り返ります。
- SwaggerはRESTful APIの仕様を記述・管理・可視化するツール群
- OpenAPI仕様はAPIの記述ルール（フォーマット）そのもの
- もともとSwagger仕様と呼ばれていたものが、現在はOpenAPI仕様として標準化されている
- YAMLで仕様を書くことでドキュメントを自動生成できる
Swaggerを導入することで、API仕様の管理が格段にしやすくなります。まずはSwagger Editorにアクセスして、既存のサンプルを触りながら雰囲気をつかんでいただけたらと思います。