How to Document a GraphQL API
Step-by-step guide to creating GraphQL API documentation with servers, auth schemes, custom scalars, operations (queries, mutations, subscriptions), and embedded examples.
Goal
Create full documentation for a GraphQL API, including server configuration, authentication schemes, custom scalar definitions, operations (queries, mutations, subscriptions) with arguments and return types, and example queries that appear in the published documentation site.
Step 1: Create a GraphQL API Definition
Step 2: Configure Servers
Step 3: Set Up Authentication Schemes
GraphQL API definitions support the same authentication scheme types as REST APIs, configured via the Security accordion.
| Auth Scheme Type | Key Configuration Fields |
|---|---|
| HTTP (Bearer/Basic) | Scheme type (bearer, basic, digest), bearer format (e.g. JWT), description |
| API Key | Key name, location (header, query, cookie), description |
| OAuth2 | Flow type (authorization code, client credentials, password, implicit), URLs, scopes |
| OpenID Connect | Discovery URL (.well-known/openid-configuration), description |
| Mutual TLS | Description of certificate requirements |
Step 4: Define Custom Scalars
If your GraphQL schema uses custom scalar types beyond the built-in String, Int, Float, Boolean, and ID types, define them here.
Step 5: Add Operations
Operations are the core of GraphQL API documentation. Each operation is a separate file within the API definition directory.
| Operation Type | Purpose | Example |
|---|---|---|
| Query | Read data from the API | getProduct, listOrders, searchCustomers |
| Mutation | Create, update, or delete data | createOrder, updateProduct, deleteCustomer |
| Subscription | Receive real-time updates via WebSocket | onOrderCreated, onStockUpdated |
Step 6: Configure Arguments and Return Types
Step 7: Add Example Queries
Step 8: Embed in Documentation
Step-by-step guide to creating REST API documentation with endpoints, parameters, schemas, and security in NeoArc Studio.