GraphQL Schemas
A GraphQL service accepts its schema in either of two shapes. Both lead to the same documentation, so use whichever fits your pipeline.
Prerequisites#
- A registered service and its upload token. See Publishing a Specification.
Option 1: SDL text#
Publish the .graphql or .gql schema file that already lives next to your service source:
curl -X POST https://docs.example.com/api/v1/services/billing-api/spec \
-H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
--data-binary @schema.graphql
Option 2: introspection result#
If your pipeline queries a live GraphQL endpoint instead, publish the introspection result as JSON. Both the full {"data": {"__schema": ...}} envelope and an already-unwrapped {"__schema": ...} work. When piping one curl into another, use --data-binary @- so the JSON is not re-encoded:
curl -sS https://billing.internal/graphql \
-H "Content-Type: application/json" \
-d @introspection-query.json \
| curl -X POST https://docs.example.com/api/v1/services/billing-api/spec \
-H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @-
introspection-query.json holds the standard {"query": "query IntrospectionQuery { ... }"} body. GraphQL tooling, such as the graphql npm package's getIntrospectionQuery(), can generate the query text.
The service name#
SDL has no info.title, so the display name comes from the description directly above a schema { ... } block if there is one, otherwise from the description of the Query type:
"""Billing API"""
type Query {
invoice(id: ID!): Invoice
}
An introspection publish resolves the name the same way: __schema.description if the server sets it (most do not), otherwise the Query type's description. If neither exists, publishing to a service that has never had a version is rejected with info.title is required. A service that already has a name keeps it.
What you see#
Fields of the schema appear in the left menu and on their own pages with arguments and return types. Versions, the Change Log and overlays work as for other formats. A changed GraphQL return type is a breaking change, except when it becomes non-null.
In exports, GraphQL fields are documented with their arguments and return type, without examples or curl commands. See Export Wizard.