Logo
NeoArc Studio

Getting Started with GraphQL API Docs

Create your first GraphQL API documentation in NeoArc Studio. Configure servers, add security schemes, and document operations step by step.

This guide walks you through creating your first GraphQL API documentation in NeoArc Studio. You will create an API definition, configure a server, add a security scheme, and document a query operation.

Prerequisites

  • NeoArc Studio installed and running
  • A workspace with at least one folder
  • Basic understanding of GraphQL concepts

Creating the API Definition

API Definition Structure

The API definition file contains:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Products API",
  "description": "GraphQL API for product catalogue management",
  "version": "1.0.0",
  "servers": [
    {
      "id": "production",
      "url": "https://api.example.com/graphql",
      "description": "Production server",
      "wsUrl": "wss://api.example.com/graphql",
      "introspectionEnabled": false
    }
  ],
  "authSchemes": [],
  "defaultAuthRequirements": [],
  "customScalars": [],
  "directives": [],
  "interfaces": [],
  "tags": ["products", "catalogue"]
}

Adding a Security Scheme

Most GraphQL APIs require authentication. Let us add a Bearer token scheme.

{
  "authSchemes": [
    {
      "id": "bearerAuth",
      "type": "bearer",
      "description": "JWT token authentication",
      "bearerFormat": "JWT"
    }
  ],
  "defaultAuthRequirements": [
    [
      { "schemeId": "bearerAuth" }
    ]
  ]
}

Creating Your First Operation

Now let us add a query operation to fetch products.

Operation File Structure

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "products",
  "operationType": "query",
  "description": "Retrieves a list of products with optional filtering and pagination.",
  "returnTypeName": "[Product!]!",
  "returnTypeNullable": false,
  "returnTypeIsList": true,
  "arguments": [
    {
      "id": "arg-1",
      "name": "limit",
      "typeName": "Int",
      "nullable": true,
      "defaultValue": "10",
      "description": "Maximum number of products to return"
    },
    {
      "id": "arg-2",
      "name": "offset",
      "typeName": "Int",
      "nullable": true,
      "defaultValue": "0",
      "description": "Number of products to skip"
    }
  ],
  "exampleQuery": "query GetProducts($limit: Int, $offset: Int) {\n  products(limit: $limit, offset: $offset) {\n    id\n    name\n    price\n    inStock\n  }\n}",
  "exampleVariables": "{\n  \"limit\": 5,\n  \"offset\": 0\n}",
  "exampleResponse": "{\n  \"data\": {\n    \"products\": [\n      {\n        \"id\": \"prod-1\",\n        \"name\": \"Widget Pro\",\n        \"price\": 29.99,\n        \"inStock\": true\n      }\n    ]\n  }\n}",
  "tags": ["products", "catalogue"]
}

Adding Argument Validation

You can add validation rules to arguments to document constraints:

{
  "id": "arg-1",
  "name": "limit",
  "typeName": "Int",
  "nullable": true,
  "defaultValue": "10",
  "description": "Maximum number of products to return",
  "validation": {
    "min": 1,
    "max": 100
  }
}

Testing Your Documentation

After creating operations:

  1. Open the GraphQL API viewer to see the rendered documentation
  2. Check that operation signatures display correctly
  3. Verify example queries are syntax-highlighted
  4. Test navigation between operations

Next Steps

Now that you have created your first GraphQL API documentation: