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:
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