API Documentation Maintenance Guide

This guide explains how to maintain and update the GDELT Cloud API documentation using Mintlify.

Overview

The API documentation is automatically generated from your Next.js API routes using next-openapi-gen, which reads JSDoc comments and Zod schemas to create an OpenAPI specification that Mintlify displays.

Architecture

nextjs_/
├── app/api/               # API route handlers with JSDoc comments
├── lib/openapi-schemas.ts # Zod schemas for request/response validation
├── next.openapi.json      # OpenAPI generation configuration
├── scripts/update-docs.sh # Automation script
└── public/openapi.json    # Generated OpenAPI spec

gdelt-cloud-docs/
└── api-reference/
    └── openapi.json       # Copy of spec used by Mintlify

Quick Update Workflow

When you make API changes:

# From the nextjs_ directory
npm run update-docs

# OR manually:
cd nextjs_
npx next-openapi-gen
cp public/openapi.json ../gdelt-cloud-docs/api-reference/openapi.json

Then test the documentation:

cd gdelt-cloud-docs
npx mintlify dev --port 3333

Adding a New API Endpoint

1. Create the API Route

Create your route file in nextjs_/app/api/:

// nextjs_/app/api/example/route.ts
import { NextResponse } from 'next/server';

/**
 * Example Endpoint
 * @description This is an example endpoint description
 * @body ExampleRequestSchema
 * @response 200:ExampleResponseSchema
 * @responseSet auth
 * @auth bearer
 * @tag Examples
 * @openapi
 */
export async function POST(request: Request) {
  // Implementation
}

2. Define Zod Schemas

Add schemas to nextjs_/lib/openapi-schemas.ts:

export const ExampleRequestSchema = z.object({
  field: z.string().describe("Field description"),
});

export const ExampleResponseSchema = z.object({
  success: z.boolean(),
  data: z.any(),
});

3. Regenerate Documentation

npm run update-docs

Hiding Internal Endpoints

To exclude an endpoint from public documentation, use one of these methods:

Method 1: Remove `@openapi` tag (per-endpoint)

/**
 * Internal Endpoint
 * @description This won't appear in docs
 * @auth bearer
 * @tag Internal
 * // NO @openapi tag = hidden from docs
 */

Method 2: Add to ignoreRoutes (for entire route patterns)

Edit nextjs_/next.openapi.json:

{
  "ignoreRoutes": [
    "/admin/*",
    "/keys/*",      // Hides all /api/keys/* endpoints
    "/internal/*"
  ]
}

JSDoc Tags Reference

Required Tags

@description - Endpoint description
@openapi - Include in OpenAPI spec (omit to hide)

Optional Tags

@tag - Group endpoints (e.g., “Alerts”, “Queries”)
@auth - Authentication type: bearer, none
@body - Request body schema name
@response - Response format: {status}:{SchemaName}:{description}
@responseSet - Error response set: common, auth, public

Example with All Tags

/**
 * Create Alert
 * @description Creates a new alert rule with SQL query and frequency
 * @body CreateAlertRequestSchema
 * @response 201:AlertCreateResponseSchema:Alert created successfully
 * @response 409:ErrorResponseSchema:Alert already exists
 * @responseSet auth
 * @auth bearer
 * @tag Alerts
 * @openapi
 */
export async function POST(request: Request) {
  // ...
}

Authentication Headers

All authenticated endpoints should document the Authorization header:

/**
 * @auth bearer
 */

This automatically adds Bearer token authentication to the endpoint documentation.

Schema Best Practices

1. Use Descriptive Field Names

// Good
export const CreateAlertRequestSchema = z.object({
  name: z.string().min(1).max(100).describe("Alert name (1-100 characters)"),
  sql_query: z.string().describe("SQL query with {TIME_FILTER} placeholder"),
});

// Bad
export const CreateAlertRequestSchema = z.object({
  name: z.string(),
  query: z.string(),
});

2. Provide Default Examples

export const QueryExecuteRequestSchema = z.object({
  sql: z.string()
    .describe("SQL query to execute")
    .default("SELECT * FROM gdelt_events WHERE day >= '2025-01-01' LIMIT 10"),
});

3. Mark Optional Fields

export const UpdateAlertRequestSchema = z.object({
  name: z.string().optional().describe("New alert name"),
  enabled: z.boolean().optional().describe("Enable or disable alert"),
});

Response Sets Configuration

Response sets define common error responses in next.openapi.json:

{
  "responseSets": {
    "common": ["400", "500"],
    "auth": ["400", "401", "403", "500"],
    "public": ["400", "500"]
  }
}

Use in JSDoc: @responseSet auth

Testing Documentation Changes

1. Local Preview

cd gdelt-cloud-docs
npx mintlify dev --port 3333

Visit http://localhost:3333

2. Verify Changes

Check that:

New endpoints appear correctly
Request/response schemas are accurate
Authentication requirements are documented
Examples are helpful
Internal endpoints are hidden

3. Check for Errors

Look for:

Invalid schema references
Missing descriptions
Broken links
Incorrect default values

Common Issues

Issue: Endpoint doesn’t appear in docs

Solution: Check that:

JSDoc has @openapi tag
Route is not in ignoreRoutes
Schema names match exactly
You ran npm run update-docs

Issue: Schema validation errors

Solution:

Ensure schema is exported from openapi-schemas.ts
Check schema name matches JSDoc reference
Verify Zod syntax is correct

Issue: Changes not reflected

Solution:

Clear Mintlify cache: rm -rf gdelt-cloud-docs/.mintlify
Regenerate: npm run update-docs
Restart dev server

Production Deployment

Mintlify Deployment

Mintlify automatically deploys from your git repository when you push changes to gdelt-cloud-docs/api-reference/openapi.json.

Workflow

Make API changes in nextjs_/
Run npm run update-docs
Review changes in gdelt-cloud-docs/

Commit both repositories:

git add nextjs_/
git commit -m "feat: add new API endpoint"

cd ../gdelt-cloud-docs
git add api-reference/openapi.json
git commit -m "docs: update API documentation"

Push to trigger Mintlify deployment

Troubleshooting

Clear all caches

# Clear Next.js cache
cd nextjs_
rm -rf .next

# Clear Mintlify cache
cd ../gdelt-cloud-docs
rm -rf .mintlify node_modules/.cache

# Regenerate everything
cd ../nextjs_
npm run update-docs

Validate OpenAPI spec

# Install validator
npm install -g @apidevtools/swagger-cli

# Validate spec
swagger-cli validate gdelt-cloud-docs/api-reference/openapi.json

Additional Resources

Support

For issues with:

API functionality: Check Next.js logs and API route files
Documentation rendering: Check Mintlify docs and docs.json
Schema generation: Check openapi-schemas.ts and JSDoc comments
Deployment: Check git commits and Mintlify dashboard

Getting Started

Features

Developer Resources

​API Documentation Maintenance Guide

​Overview

​Architecture

​Quick Update Workflow

​Adding a New API Endpoint

​1. Create the API Route

​2. Define Zod Schemas

​3. Regenerate Documentation

​Hiding Internal Endpoints

​Method 1: Remove @openapi tag (per-endpoint)

​Method 2: Add to ignoreRoutes (for entire route patterns)

​JSDoc Tags Reference

​Required Tags

​Optional Tags

​Example with All Tags

​Authentication Headers

​Schema Best Practices

​1. Use Descriptive Field Names

​2. Provide Default Examples

​3. Mark Optional Fields

​Response Sets Configuration

​Testing Documentation Changes

​1. Local Preview

​2. Verify Changes

​3. Check for Errors

​Common Issues

​Issue: Endpoint doesn’t appear in docs

​Issue: Schema validation errors

​Issue: Changes not reflected

​Production Deployment

​Mintlify Deployment

​Workflow

​Troubleshooting

​Clear all caches

​Validate OpenAPI spec

​Additional Resources

​Support