Skip to content

GRAPHQL_DOCS_GENERATION.md

Latest commit

 

History

History
194 lines (134 loc) · 4.04 KB

GRAPHQL_DOCS_GENERATION.md

File metadata and controls

194 lines (134 loc) · 4.04 KB

Automatic GraphQL Documentation Generation with SpectaQL

This guide explains how to automatically generate GraphQL documentation from the schema.

Installation

SpectaQL is already installed as a development dependency. If not:

cd backend
pnpm add -D spectaql

Configuration

The SpectaQL configuration is located in backend/spectaql.config.yml.

Main Options

  • schema.file: Path to the GraphQL schema file (src/graphql/schema.gql)
  • targetDir: Output directory for documentation (docs/graphql)
  • baseUrl: Base URL of the API (default: http://localhost:4000)
  • title: Documentation title
  • description: API description

Generating Documentation

Single Generation

cd backend
pnpm docs:generate

This command:

  1. Reads the GraphQL schema from src/graphql/schema.gql
  2. Generates HTML documentation in docs/graphql/
  3. Creates an index.html file that you can open in a browser

Watch Mode (Development)

cd backend
pnpm docs:watch

This command watches for schema changes and automatically regenerates the documentation.

Accessing the Documentation

Once generated, open the file:

docs/graphql/index.html

In your browser, or serve it with a local HTTP server:

# With Python
cd docs/graphql
python3 -m http.server 8000

# With Node.js (http-server)
npx http-server docs/graphql -p 8000

Then access http://localhost:8000

Integration in Workflow

Automatic Generation After Build

The GraphQL schema is automatically generated by NestJS when the application starts. To generate documentation after each build:

  1. Add to your CI/CD:
- name: Generate GraphQL Documentation
  run: |
    cd backend
    pnpm docs:generate
  1. Or create a build script that includes generation:
{
  "scripts": {
    "build:docs": "pnpm build && pnpm docs:generate"
  }
}

Schema Updates

The GraphQL schema (src/graphql/schema.gql) is automatically generated by NestJS from your resolvers and entities. It updates:

  • When starting the application in development mode
  • When running pnpm start:dev

To force regeneration:

cd backend
pnpm start:dev
# The schema will be regenerated, then:
pnpm docs:generate

Customization

Modify Style

Edit backend/spectaql.config.yml to customize:

  • title: Documentation title
  • description: API description
  • introText: Introduction text (Markdown supported)
  • footerText: Footer text
  • logoFile: Path to a logo file
  • faviconFile: Path to a favicon file

Display Options

In spectaql.config.yml, you can hide/show different sections:

  • hideSearch: Hide search bar
  • hideSchema: Hide complete schema
  • hideExamples: Hide examples
  • hideDeprecated: Hide deprecated elements
  • hideInternal: Hide internal elements

Example Custom Configuration

schema:
  file: ./src/graphql/schema.gql
targetDir: ./docs/graphql
baseUrl: https://api.epitrello.com
title: Epitrello API - Complete Documentation
description: GraphQL API for Trello-like project management
introText: |
  # Welcome to Epitrello Documentation

  This API allows you to manage boards, lists, cards, and workspaces.
logoFile: ./assets/logo.png
hideDeprecated: true
hideInternal: true

Troubleshooting

Error: "Schema file not found"

Make sure the GraphQL schema exists:

cd backend
ls -la src/graphql/schema.gql

If the file doesn't exist, start the application once to generate it:

pnpm start:dev
# Wait for the application to start, then stop it (Ctrl+C)

Documentation Not Updated

If the documentation doesn't reflect recent changes:

  1. Check that the schema is up to date:

    cd backend
pnpm start:dev

  2. Regenerate the documentation:

    pnpm docs:generate

Path Issues

If you have path errors, use absolute paths or make sure you're running the command from the correct directory (backend/).

Resources