GraphQL Operations
Document queries, mutations, and subscriptions with full support for arguments, return types, validation, examples, and complexity hints.
GraphQL operations are the core of your API documentation. The dedicated editor supports documenting queries, mutations, and subscriptions with full support for arguments, return types, examples, and metadata.
Operation Types
GraphQL defines three operation types, each serving a distinct purpose:
Operation Properties
Every operation has these configurable properties:
| Property | Required | Description |
|---|---|---|
| name | Yes | The GraphQL field name (e.g., "products", "createOrder") |
| operationType | Yes | One of: query, mutation, subscription |
| description | No | Rich text explanation of the operation's purpose |
| arguments | No | Input parameters with types and validation |
| returnTypeName | No | GraphQL type signature (e.g., "[Product!]!") |
| returnTypeSchemaRef | No | Reference to a schema definition |
| deprecated | No | Mark operation as deprecated with reason |
| complexity | No | Numeric complexity score for rate limiting |
| exampleQuery | No | Example GraphQL operation in SDL format |
| exampleVariables | No | Example variables JSON |
| exampleResponse | No | Example response JSON |
| authRequirements | No | Operation-level security override |
| tags | No | Categorisation tags |
| triggerDescription | No | Event trigger explanation (subscriptions only) |
Return Types
Operations return typed data. Configure return types using either:
- Direct Type Name - GraphQL type signature like "User", "[Product!]!", or "Boolean"
- Schema Reference - Link to a schema definition for complex types
Return type modifiers:
- Nullable - Whether the return value can be null
- List - Whether the operation returns an array
- List Item Nullable - Whether items within the list can be null
# Non-null user
user(id: ID!): User!
# Nullable list of non-null products
products(limit: Int): [Product!]
# Non-null list of nullable users
allUsers: [User]!
# Non-null list of non-null strings
tags: [String!]!Operation Examples
Provide examples to help consumers understand how to use your API:
{
"exampleQuery": "query GetUser($id: ID!) {\n user(id: $id) {\n id\n name\n email\n createdAt\n }\n}",
"exampleVariables": "{\n \"id\": \"user-123\"\n}",
"exampleResponse": "{\n \"data\": {\n \"user\": {\n \"id\": \"user-123\",\n \"name\": \"Jane Smith\",\n \"email\": \"[email protected]\",\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n }\n}"
}Editor Interface
The operation editor provides six tabs:
- Basics - Name, type, description, trigger description (subscriptions)
- Arguments - Input parameters with types, validation, and lineage
- Return Type - Output type configuration and schema reference
- Examples - Query, variables, and response examples
- Security - Authentication override configuration
- Metadata - Tags, links, complexity, deprecation