How to Document a GraphQL API

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.

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.

Step 6: Configure Arguments and Return Types

Step 7: Add Example Queries

Step 8: Embed in Documentation