GraphQL API Documentation
Document GraphQL APIs with queries, mutations, subscriptions, custom scalars, directives, interfaces, and per-operation authentication in NeoArc Studio.
The GraphQL editor documents GraphQL APIs alongside your architecture content. Define server configuration, authentication schemes, operations, custom scalars, directives, and interfaces in a structured format that publishes as a browsable API reference on your documentation site.
Server Configuration
Each GraphQL API definition includes server configuration with fields specific to GraphQL endpoints:
| Property | Description |
|---|---|
| URL | The primary GraphQL endpoint (e.g. https://api.example.com/graphql) |
| WebSocket URL | Separate WebSocket endpoint for subscriptions |
| Health Check URL | Optional health check endpoint for monitoring |
| Introspection Toggle | Whether the server allows introspection queries |
Authentication Schemes
Define how clients authenticate with the GraphQL API. Four scheme types are supported:
Set default authentication requirements at the API level. Individual operations override the default when they require a different scheme or additional scopes.
Operations
Document every query, mutation, and subscription your API exposes. Each operation captures a full set of details:
Operation Properties
| Property | Description |
|---|---|
| Name and Type | Operation name and type (query, mutation, subscription) |
| Description | Rich text description of what the operation does |
| Arguments | Typed arguments with nullability, list support, validation rules, default values, and optional data lineage |
| Return Type | Type reference or direct type name with nullability and list indicators |
| Deprecation | Mark operations as deprecated with a reason string |
| Complexity | Numeric complexity hint for rate limiting and cost analysis |
| Example Query | SDL-format example of how to call the operation |
| Example Variables | JSON variables to accompany the example query |
| Example Response | Expected JSON response for the example query |
| Auth Override | Per-operation authentication requirements that override the API default |
Custom Scalars
Document custom scalar types defined in the GraphQL schema. Each scalar records its name, specification URL (e.g. RFC 3339 for DateTime), serialisation format, example values, and coercion rules (which types coerce to and from this scalar).
Directives
Define directive metadata for the API. Each directive specifies its valid locations across both executable and type system categories, arguments, whether it is repeatable, and whether it is a built-in directive.
| Location Category | Locations |
|---|---|
| Executable | QUERY, MUTATION, SUBSCRIPTION, FIELD, FRAGMENT_DEFINITION, FRAGMENT_SPREAD, INLINE_FRAGMENT, VARIABLE_DEFINITION |
| Type System | SCHEMA, SCALAR, OBJECT, FIELD_DEFINITION, ARGUMENT_DEFINITION, INTERFACE, UNION, ENUM, ENUM_VALUE, INPUT_OBJECT, INPUT_FIELD_DEFINITION |
Interfaces
Document GraphQL interface definitions with their required fields. Each interface lists its fields (with type, nullability, list support, and arguments) and which other interfaces it implements. Directives applied to the interface or its fields are also captured.
SDL Export
Export your GraphQL API documentation to the standard Schema Definition Language (SDL) format. The export generates a complete .graphql schema file with type definitions, queries, mutations, subscriptions, custom scalars, directives, and interfaces. Use the exported SDL with code generation tools, schema registries, and other GraphQL ecosystem tools.
Viewer
The published site includes a GraphQL API browser panel that presents all documented APIs. Readers navigate by operation type, browse individual operations with their full details, and view custom scalars, directives, and interfaces in context.
Use Cases
Document REST APIs with full endpoint specifications, OpenAPI import and export, seven HTTP methods, parameters, request and response bodies linked to shared schemas, authentication schemes, and a published API browser. REST is part of the API documentation suite (REST, GraphQL, gRPC, AsyncAPI, Webhooks, MCP) sharing a unified schema layer.
Document event-driven and asynchronous APIs with channels, operations, messages, protocol bindings across a wide range of protocols, security schemes, reusable traits, and AsyncAPI 3.0 export in NeoArc Studio.
Document webhook-based integrations with event definitions, HMAC signature verification, delivery guarantees, retry policies, dead letter queues, circuit breakers, and consumer guidance. The structured webhook editor captures what architects need to express about push-based event notifications.
Define data structures with field types covering strings, numbers, booleans, objects, arrays and more, type specialisations for fine-grained modelling, and validation rules covering type safety, cardinality, referential integrity and cross-field constraints. Create reusable schemas that stay synchronised across your documentation.