[章番号]: GraphQL API仕様書

このテンプレートの使い方

このファイルは、GraphQL APIの仕様を定義するためのテンプレートです。 GraphQLの仕様はスキーマ定義が中心となるため、このドキュメントはスキーマへの参照と、主要なクエリ/ミューテーションの具体的な使用例を示すことに重点を置きます。 詳しい使い方は「設計仕様の書き方ガイド」を参照してください。

1. はじめに

1.1. 目的

1.2. 対象読者

2. 基本情報

項目	内容
エンドポイントURL (Production)	https://api.example.com/graphql
エンドポイントURL (Staging)	https://staging.api.example.com/graphql
認証方式	[例: AuthorizationヘッダにBearerトークンを設定] (詳細はAPI設計共通ガイドラインを参照)

3. スキーマ定義

スキーマ全体の定義は以下のファイルを参照してください。

• schema.graphql

3.1. 主要な型 (Types)

• User: ユーザー情報を表す型。
• Post: 投稿情報を表す型。

---

4. クエリ (Queries)

4.1. user

• 概要: IDを指定して単一のユーザー情報を取得する。
• スキーマ:

user(id: ID!): User

• 使用例:

query GetUserById($userId: ID!) {
    user(id: $userId) {
        id
        name
        email
        posts {
            id
            title
        }
    }
}

• 変数例:

{
    "userId": "user-001"
}

---

5. ミューテーション (Mutations)

5.1. createPost

• 概要: 新しい投稿を作成する。
• スキーマ:

createPost(title: String!, content: String!): Post

• 使用例:

mutation CreateNewPost($title: String!, $content: String!) {
    createPost(title: $title, content: $content) {
        id
        title
        content
        author {
            id
            name
        }
    }
}

• 変数例:

{
    "title": "GraphQLは素晴らしい",
    "content": "スキーマ駆動開発は最高です..."
}

---

6. サブスクリプション (Subscriptions)

6.1. postAdded

• 概要: 新しい投稿が作成された際にリアルタイムで通知を受け取る。
• スキーマ:

postAdded: Post

• 使用例:

subscription OnPostAdded {
    postAdded {
        id
        title
        author {
            name
        }
    }
}

7. エラーハンドリング

GraphQLの標準的なerrors配列形式で返されます。

{
    "errors": [
        {
            "message": "Post with ID 'post-999' not found.",
            "locations": [{ "line": 2, "column": 3 }],
            "path": ["post"],
            "extensions": {
                "code": "NOT_FOUND",
                "timestamp": "2025-07-28T12:00:00Z"
            }
        }
    ],
    "data": {
        "post": null
    }
}