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#

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.

Next steps#

Last updated: