GraphQL API Documentation
Document GraphQL APIs with full support for queries, mutations, subscriptions, custom scalars, directives, and interfaces. Configure authentication with OAuth2, API keys, and custom headers.
The GraphQL API documentation tooling covers the full schema surface. Document your GraphQL schema with full support for operations (queries, mutations, subscriptions), custom scalars, directives, and interfaces. Configure authentication using OAuth2, API keys, bearer tokens, or custom headers.
Why Document GraphQL APIs in NeoArc
- Visual Editors - Define operations, scalars, directives, and interfaces through dedicated editors rather than hand-editing SDL files
- Schema Integration - Reference your data schemas for argument and return types
- Full Security Support - Configure Bearer tokens, API keys, OAuth2 with scopes, and custom headers
- Subscription Support - Document real-time operations with trigger descriptions and WebSocket configuration
- Directive System - Define custom directives with all standard GraphQL locations supported
- Data Lineage - Trace API fields back to source schemas and entities
GraphQL Editors
Dedicated editors are available for each aspect of GraphQL API documentation:
| Editor | Purpose | Key Features |
|---|---|---|
| API Home | Top-level API definition | Name, version, servers, WebSocket URLs, default security |
| Operations | Queries, mutations, subscriptions | Arguments, return types, examples, complexity hints, auth overrides |
| Security Schemes | Authentication configuration | Bearer, API Key, OAuth2 (2 flows), custom headers |
| Custom Scalars | Extended type system | Specification URLs, serialisation format, coercion rules |
| Directives | Schema decorators | All standard locations, arguments with types, repeatable flag |
| Interfaces | Type contracts | Fields, interface inheritance, field-level directives |
Operation Types
GraphQL defines three operation types, each with specific purposes:
Storage
A GraphQL API lives in a single .projection.json file with profileType: 'api' and apiType: 'graphql'. Server and auth configuration, custom scalars, directives and interfaces are carried on apiProfile.protocolMetadata. Each query, mutation and subscription is a projection entity with entityKind: 'graphql-operation'. Type definitions (objects, interfaces, enums) live in a separate schema projection that the GraphQL projection sources - this lets multiple APIs share the same type library.
Getting Started
Ready to document your first GraphQL API? Follow the getting started guide to create an API definition, configure security, and add operations.