How should I document a GraphQL API with examples and auth?

A good GraphQL API doc should make it easy to answer four questions fast:

1. How do I authenticate?
2. What can I query/mutate?
3. What does the response look like?
4. What are common examples and edge cases?

Here’s a practical structure you can follow.

---

1) Start with a short overview

Include:

• What the API is for
• Base endpoint
• GraphQL playground / explorer link
• Environments, if relevant

Example

# Acme GraphQL API

Base URL: `https://api.acme.com/graphql`

Use this API to manage customers, orders, and subscriptions.

---

2) Document authentication clearly

GraphQL auth is usually handled at the HTTP layer, so document it near the top.

Include:

• Auth type: Bearer token, API key, OAuth2, session cookie, etc.
• Where to send it: Authorization header, custom header, cookies
• How to get credentials
• Scope/role requirements
• Example request

Example

## Authentication

All requests require a bearer token.

Header:

```http
Authorization: Bearer <your_access_token>

Example:

curl https://api.acme.com/graphql \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  --data '{"query":"{ me { id email } }"}'

Permissions

• read:customers to query customers
• write:orders to create orders

If auth failures differ by case, document the errors:
- `401 Unauthorized` for missing/invalid token
- `403 Forbidden` for valid token without permission

---

## 3) Explain GraphQL basics for your API

Not everyone knows GraphQL well. Add a short section about:

- Queries vs mutations
- Fields and nested selection
- Variables
- Pagination
- Errors

**Example**

```md
## GraphQL basics

- `query` retrieves data
- `mutation` changes data
- Use variables instead of hardcoding values
- Request only the fields you need

---

4) Document the schema by type, not only by endpoint

GraphQL is best documented by:

• Query
• Mutation
• object types
• input types
• enums
• interfaces/unions

For each field, include:

• Name
• Description
• Arguments
• Return type
• Required permissions
• Example usage

Example field documentation

### Query.customer(id: ID!): Customer

Fetch a customer by ID.

**Permissions:** `read:customers`

**Arguments**
- `id` (ID!, required): Customer ID

**Example**

```graphql
query GetCustomer($id: ID!) {
  customer(id: $id) {
    id
    name
    email
  }
}

Variables

{ "id": "cus_123" }

Response

{
  "data": {
    "customer": {
      "id": "cus_123",
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }
  }
}

---

## 5) Include full request/response examples

For each major operation, show:

- GraphQL operation
- Variables
- HTTP request example
- Successful response
- Error response

### Query example

```graphql
query ListOrders($first: Int!, $after: String) {
  orders(first: $first, after: $after) {
    edges {
      node {
        id
        total
        status
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

{
  "first": 10,
  "after": null
}

Mutation example

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    order {
      id
      status
      total
    }
    userErrors {
      field
      message
    }
  }
}

{
  "input": {
    "customerId": "cus_123",
    "items": [
      { "productId": "prod_1", "quantity": 2 }
    ]
  }
}

---

6) Document errors in GraphQL-specific terms

GraphQL errors can be tricky because:

• HTTP status may still be 200
• Errors may appear in an errors array
• Partial data may still be returned

Explain:

• Standard error format
• Common error codes
• Field-level validation errors
• Authorization errors
• Rate-limit behavior

Example

## Errors

GraphQL responses may include both `data` and `errors`.

Example:

```json
{
  "data": {
    "customer": null
  },
  "errors": [
    {
      "message": "Customer not found",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

Common codes:

• UNAUTHENTICATED
• FORBIDDEN
• NOT_FOUND
• BAD_USER_INPUT
• RATE_LIMITED

---

## 7) Document pagination, filtering, and sorting

These are often the hardest parts for consumers.

If you use cursor pagination, explain:
- `first`, `after`
- `last`, `before`
- `pageInfo`
- max page sizes

If you support filters/sorting, show the input objects and examples.

---

## 8) Show schema examples for reusable types

Document each reusable type once.

**Example**

```md
### Customer

A customer in Acme.

| Field | Type | Description |
|------|------|-------------|
| `id` | `ID!` | Unique customer ID |
| `name` | `String!` | Full name |
| `email` | `String!` | Email address |
| `createdAt` | `DateTime!` | Creation timestamp |

---

9) Add “common workflows” or “recipes”

These are more useful than field lists alone.

Examples:

• Authenticate and fetch current user
• Create customer then create order
• Handle pagination through all items
• Refresh token flow
• Webhook/event subscriptions, if applicable

---

10) Keep auth examples close to real usage

For every example request, show the auth header if needed.

cURL example

curl https://api.acme.com/graphql \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { me { id email } }"}'

JavaScript example

const res = await fetch("https://api.acme.com/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    query: `
      query {
        me { id email }
      }
    `,
  }),
});

---

11) Include introspection or generated docs if possible

Best practice is to generate docs from the schema so they stay in sync:

• GraphQL introspection
• GraphQL SDL comments
• Code-first schema annotations
• Tools like GraphQL Playground, Apollo Studio, Redocly GraphQL, SpectaQL, GraphDoc, etc.

Still add human-written docs for:

• auth
• workflows
• examples
• business rules
• rate limits

---

Recommended doc outline

You can use this template:

# API Overview
# Authentication
# Getting Started
# GraphQL Basics
# Schema Reference
  - Query
  - Mutation
  - Types
  - Inputs
  - Enums
# Errors
# Pagination
# Rate Limits
# Examples / Recipes
# Changelog
# Support

---

Best practices

• Use realistic examples with real shapes, not toy data only
• Mark required fields clearly
• Include variables in examples
• Show success and failure responses
• Explain permissions per field or operation
• Keep docs synchronized with schema changes
• Prefer copy-pasteable snippets
• Avoid huge autogenerated dumps without explanation

---

If you want, I can also give you:

1. a Markdown template for GraphQL API docs, or
2. an example of Swagger-like docs for GraphQL with auth and sample queries.