# GraphQL Parser

This directory contains the GraphQL schema parsing logic for Brainfish API Docs.

## Structure

- `types.ts` - TypeScript types for GraphQL schema representation
- `parser.ts` - GraphQL SDL parsing using graphql-js
- `transformer.ts` - Convert GraphQL schema to BrainfishCollection
- `index.ts` - Main entry point and exports

## Dependencies Required

```bash
npm install graphql
```

## Usage

### Parse GraphQL Schema

```typescript
import { importGraphQLSchema } from '@/lib/api-docs/parsers/graphql'

// Parse SDL string
const collection = await importGraphQLSchema(sdlString, {
  name: 'My GraphQL API',
  endpoint: 'https://api.example.com/graphql',
})
```

### Get Full Schema Information

```typescript
import { importGraphQLSchemaFull } from '@/lib/api-docs/parsers/graphql'

const graphqlCollection = await importGraphQLSchemaFull(sdlString, {
  name: 'My GraphQL API',
  endpoint: 'https://api.example.com/graphql',
})

// Access queries, mutations, subscriptions, and types
console.log(graphqlCollection.queries)
console.log(graphqlCollection.mutations)
console.log(graphqlCollection.types)
```

### Parse Schema Only

```typescript
import { parseGraphQL } from '@/lib/api-docs/parsers/graphql'

const schema = await parseGraphQL(sdlString)

// Access schema information
console.log(schema.info)
console.log(schema.types)
console.log(schema.queries)
```

## Configuration in docs.json

Add a GraphQL tab to your navigation:

```json
{
  "navigation": {
    "tabs": [
      {
        "tab": "GraphQL API",
        "type": "graphql",
        "path": "/graphql",
        "schema": "api-reference/schema.graphql",
        "endpoint": "https://api.example.com/graphql"
      }
    ]
  }
}
```

### Multiple Schemas

```json
{
  "navigation": {
    "tabs": [
      {
        "tab": "GraphQL API",
        "type": "graphql",
        "path": "/graphql",
        "schemas": [
          {
            "name": "Public API",
            "schema": "api-reference/public.graphql",
            "endpoint": "https://api.example.com/graphql",
            "default": true
          },
          {
            "name": "Admin API",
            "schema": "api-reference/admin.graphql",
            "endpoint": "https://admin.example.com/graphql"
          }
        ]
      }
    ]
  }
}
```

## Features

- **SDL Parsing**: Parse GraphQL Schema Definition Language files
- **Introspection**: Support for introspection query results (planned)
- **Type Explorer**: View all types, inputs, enums, interfaces, unions
- **Operation Playground**: Test queries, mutations, and subscriptions
- **Variable Support**: Auto-generate example variables from schema
- **Documentation**: Extract descriptions from schema for docs

## Architecture

The GraphQL parser follows the same pattern as the OpenAPI parser:

1. **Parse**: Read SDL or introspection result
2. **Validate**: Ensure schema is valid GraphQL
3. **Transform**: Convert to internal types
4. **Export**: Generate BrainfishCollection for UI

This allows GraphQL APIs to use the same documentation UI as REST APIs,
with GraphQL-specific enhancements for the schema explorer and playground.
