API仕様書（OpenAPI）入門

OpenAPIとは？

OpenAPI Specification（OAS）は、 REST APIの仕様を記述するための標準フォーマットです。 以前はSwaggerとして知られていましたが、 現在はLinux Foundation傘下のOpenAPI Initiativeが管理しています。

YAML（またはJSON）でAPIのエンドポイント、リクエスト/レスポンスの形式、 認証方法などを定義することで、フロントエンドとバックエンドの開発者が 共通の仕様書をもとに並行開発できるようになります。

学習ロードマップ

このコースでは、API仕様書の基礎からツール活用まで段階的に学びます。

• API仕様書の基本 — OpenAPIとは何か、API-first開発の考え方を理解する
• OpenAPIの書き方 — paths、schemas、parametersなどの定義を実践する
• ツールと自動生成 — Swagger UI、コード生成、バリデーションを活用する

最初のOpenAPI定義

OpenAPIでは、YAMLまたはJSONでAPIの仕様を記述します。以下は最もシンプルなOpenAPI定義の例です。

openapi: "3.0.3"
info:
  title: My First API
  version: "1.0.0"
  description: はじめてのOpenAPI定義

paths:
  /hello:
    get:
      summary: 挨拶を返す
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hello, World!"

各レッスンで、仕様書の書き方からツール活用まで順を追って学んでいきます。