API仕様管理比較：OpenAPI/Swagger vs AsyncAPI vs GraphQL Schema でAPIドキュメントを管理する

📄 REST・イベント駆動・GraphQLのAPIを適切な仕様フォーマットで管理する方法を解説します。OpenAPI・AsyncAPI・GraphQL SDL（Schema Definition Language）を比較します。

API仕様管理の重要性

API仕様はフロントエンド・バックエンドチームのインターフェース契約です。ドキュメント・コード生成・テスト自動化の基盤となります。

主要フォーマット比較表

項目	OpenAPI 3.x	AsyncAPI 3.x	GraphQL SDL
対象API	REST/HTTP	イベント駆動/WebSocket	GraphQL
フォーマット	YAML/JSON	YAML/JSON	SDL（独自）
コード生成	◎	◎	◎
UI	Swagger UI	AsyncAPI Playground	GraphiQL
バリデーション	◎	◎	◎
ユーザー数	◎ 最多	○	◎

各フォーマット・ツールの特徴

OpenAPI 3.x（旧Swagger）

RESTful APIの事実上標準仕様。YAML/JSONで書いたスキーマからドキュメント・クライアントコードを自動生成できます。

主な特徴:

• 業界標準（Swagger Tools・Stoplight・Postman等が対応）
• Swagger UI・ReDoc・Elements等でインタラクティブドキュメント
• openapi-generator-cli で50以上の言語のクライアントSDK生成
• プリミティブなリクエスト/レスポンスのバリデーション

# openapi.yaml
openapi: "3.0.3"
info:
  title: My API
  version: "1.0.0"
paths:
  /articles:
    get:
      summary: 記事一覧取得
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [devops, llm-tools, security]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
    post:
      summary: 記事作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateArticle'
      responses:
        "201":
          description: 作成成功
components:
  schemas:
    Article:
      type: object
      required: [id, title, slug]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        slug:
          type: string
        category:
          type: string
    CreateArticle:
      type: object
      required: [title, content_md]
      properties:
        title:
          type: string
        content_md:
          type: string

# Swagger UIをDockerで起動
docker run -d -p 8080:8080   -e SWAGGER_JSON=/api/openapi.yaml   -v $(pwd)/openapi.yaml:/api/openapi.yaml   swaggerapi/swagger-ui

# クライアントコード生成（TypeScript）
openapi-generator-cli generate   -i openapi.yaml   -g typescript-fetch   -o ./src/api-client

向いているケース: REST API・最大のエコシステム

AsyncAPI 3.x

Kafka・WebSocket・MQTT・AMQPなどのイベント駆動・非同期APIの仕様記述フォーマット。マイクロサービス間のイベント設計のドキュメントに使います。

主な特徴:

• OpenAPIと似た構文でイベント駆動APIを記述
• Kafka・RabbitMQ・WebSocket・SSE等に対応
• AsyncAPI Studio（ビジュアルエディタ）
• コード生成（modelina）でメッセージスキーマのPOJOを生成

# asyncapi.yaml
asyncapi: "3.0.0"
info:
  title: Order Events API
  version: "1.0.0"
channels:
  order/created:
    address: order.created
    messages:
      OrderCreated:
        $ref: '#/components/messages/OrderCreated'
  order/shipped:
    address: order.shipped
    messages:
      OrderShipped:
        $ref: '#/components/messages/OrderShipped'
operations:
  publishOrderCreated:
    action: send
    channel:
      $ref: '#/channels/order~1created'
  receiveOrderShipped:
    action: receive
    channel:
      $ref: '#/channels/order~1shipped'
components:
  messages:
    OrderCreated:
      payload:
        type: object
        properties:
          orderId:
            type: string
          userId:
            type: string
          items:
            type: array
            items:
              type: object
              properties:
                productId:
                  type: string
                quantity:
                  type: integer

向いているケース: Kafka・WebSocket・マイクロサービスイベント設計

GraphQL SDL

GraphQLのスキーマ定義言語（Schema Definition Language）。GraphQLサーバーの型システムを記述する言語で、型安全なAPIを定義します。

主な特徴:

• 強力な型システム（カスタムスカラー・Union・Interface）
• イントロスペクションでスキーマを動的取得
• GraphiQL・Apollo Sandboxでインタラクティブに探索
• コード生成（graphql-codegen）でクライアントの型を自動生成

# schema.graphql
type Query {
  articles(
    category: Category
    limit: Int = 10
    offset: Int = 0
  ): [Article!]!

  article(slug: String!): Article
}

type Mutation {
  createArticle(input: CreateArticleInput!): Article!
  updateArticle(id: ID!, input: UpdateArticleInput!): Article!
}

type Subscription {
  articlePublished: Article!
}

type Article {
  id: ID!
  title: String!
  slug: String!
  category: Category!
  tags: [String!]!
  contentMd: String!
  createdAt: DateTime!
}

input CreateArticleInput {
  title: String!
  slug: String!
  category: Category!
  contentMd: String!
}

enum Category {
  DEVOPS
  SECURITY
  LLM_TOOLS
  LOW_CODE
}

scalar DateTime

# graphql-codegenでTypeScriptの型を生成
npx graphql-codegen --config codegen.yml

# codegen.yml
schema: https://api.example.com/graphql
documents: './src/**/*.graphql'
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations

向いているケース: GraphQL API・型安全なクライアント

API種別×フォーマットの選択マトリクス

APIタイプ	推奨フォーマット
REST HTTP API	OpenAPI 3.x
Kafka/WebSocket/MQTT	AsyncAPI 3.x
GraphQL	GraphQL SDL
gRPC	Protocol Buffers

内部リンク

• OSSのAPIゲートウェイ比較
• GraphQLエンジン比較

外部リソース

• OpenAPI Specification 公式↗
• AsyncAPI 公式サイト↗
• GraphQL 公式ドキュメント↗
• graphql-codegen 公式ドキュメント↗

FAQ

Q. OpenAPI 2.0（Swagger 2.0）とOpenAPI 3.0はどちらを使うべきですか？

新規プロジェクトはOpenAPI 3.1（最新）を使ってください。3.xはJSON Schema準拠で表現力が大幅に向上しています。

Q. REST APIにOpenAPIを後付けで追加できますか？

はい。Postman・Insomnia等のコレクションからエクスポートする方法や、既存コードからスキーマを自動抽出するライブラリ（fastapi、SpringDoc等）があります。

Q. AsyncAPIはKafkaのトピックスキーマ管理に使えますか？

はい。Kafka + Avro/JSON Schemaの組み合わせでAsyncAPIを使うケースが増えています。Confluent Schema Registryとも連携できます。

Q. GraphQLとREST、どちらを選ぶべきですか？

フロントエンドが必要なフィールドだけを取得したい（アンダーフェッチ/オーバーフェッチを避けたい）場合はGraphQL。シンプルなCRUDAPIや公開APIはRESTが適切です。