ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-API-002API

GraphQL endpoint documented in OpenAPI

Checks that GraphQL endpoint exposure is documented when OpenAPI is used as the API review artifact.

errorsetup-gapNo auto-fix

How to fix

  1. Document the GraphQL endpoint in the API contract.
  2. Regenerate the OpenAPI artifact if it is generated.
  3. Add review notes for schema compatibility if GraphQL schema files live separately.

What it means

A GraphQL endpoint exists but the public API contract does not document how clients reach it.

Why it matters

Undocumented API surfaces bypass review and make compatibility expectations unclear.

Common causes

  • GraphQL was added after REST contract generation.
  • The endpoint is mounted outside the documented API routes.
  • The OpenAPI document excludes the GraphQL transport endpoint.

Example bad pattern

/graphql is mounted in code but absent from the API contract.

Example good pattern

The API contract documents the GraphQL endpoint and links to schema review artifacts.

Related files/config

  • contracts/openapi.yaml
  • apps/api/src

Related CLI commands

  • archpilot validate
  • archpilot validate --ci

Related docs

Rule CatalogGitHub CI IntegrationValidation & Findings
AP-API-002 - GraphQL endpoint documented in OpenAPI | ArchPilot Docs