OpenAPI Quick Reference Guide

A quick reference for understanding and maintaining the Dialgen OpenAPI specification.

📋 Table of Contents

File Structure
OpenAPI Specification Sections
Common Tasks
Schema Patterns
Response Codes
Validation

📁 File Structure

dialgen-docs/
├── openapi.json              # Main OpenAPI 3.0 specification
├── docs.json                 # Mintlify configuration (references openapi.json)
└── api-reference/
    └── introduction.mdx      # API introduction page

🔧 OpenAPI Specification Sections

1. Info Section

{
  "openapi": "3.0.3",
  "info": {
    "title": "Dialgen API",
    "description": "API description",
    "version": "1.0.0",
    "contact": {
      "name": "Dialgen Support",
      "url": "https://sa.dialgen.ai"
    }
  }
}

2. Servers Section

{
  "servers": [
    {
      "url": "https://sa.dialgen.ai",
      "description": "Production server"
    }
  ]
}

3. Security Section

{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token authentication"
      }
    }
  }
}

4. Paths Section

Defines all API endpoints:

{
  "paths": {
    "/api/v1/endpoint": {
      "get": {
        "summary": "Endpoint summary",
        "description": "Detailed description",
        "operationId": "uniqueOperationId",
        "tags": ["Category"],
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

5. Components Section

Reusable schemas, responses, and parameters:

{
  "components": {
    "schemas": {
      "SchemaName": {...}
    },
    "responses": {
      "ResponseName": {...}
    },
    "parameters": {
      "ParameterName": {...}
    }
  }
}

🛠️ Common Tasks

Adding a New Endpoint

Add to paths section:

{
  "paths": {
    "/api/v1/new-endpoint": {
      "post": {
        "summary": "New Endpoint",
        "description": "Description here",
        "operationId": "newEndpoint",
        "tags": ["Category"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}

Add schemas:

{
  "components": {
    "schemas": {
      "NewRequest": {
        "type": "object",
        "required": ["field1"],
        "properties": {
          "field1": {
            "type": "string",
            "description": "Field description"
          }
        }
      },
      "NewResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}

Update docs.json navigation:

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "Category",
            "pages": [
              "POST /api/v1/new-endpoint"
            ]
          }
        ]
      }
    ]
  }
}

Adding Query Parameters

{
  "parameters": [
    {
      "name": "paramName",
      "in": "query",
      "description": "Parameter description",
      "required": true,
      "schema": {
        "type": "string",
        "example": "example-value"
      }
    }
  ]
}

Adding Request Body

{
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RequestSchema"
        },
        "example": {
          "field": "value"
        }
      }
    }
  }
}

Adding Response

{
  "responses": {
    "200": {
      "description": "Success description",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResponseSchema"
          },
          "example": {
            "success": true,
            "data": {}
          }
        }
      }
    }
  }
}

📊 Schema Patterns

Basic Object Schema

{
  "SchemaName": {
    "type": "object",
    "required": ["field1", "field2"],
    "properties": {
      "field1": {
        "type": "string",
        "description": "Field description"
      },
      "field2": {
        "type": "number",
        "minimum": 0,
        "maximum": 100
      }
    }
  }
}

Array Schema

{
  "ArraySchema": {
    "type": "array",
    "items": {
      "$ref": "#/components/schemas/ItemSchema"
    },
    "minItems": 1,
    "maxItems": 100
  }
}

Enum Schema

{
  "StatusSchema": {
    "type": "string",
    "enum": ["PENDING", "PROCESSING", "COMPLETED", "FAILED"],
    "description": "Status of the operation"
  }
}

Nested Object Schema

{
  "ParentSchema": {
    "type": "object",
    "properties": {
      "childObject": {
        "type": "object",
        "properties": {
          "nestedField": {
            "type": "string"
          }
        }
      }
    }
  }
}

Schema with Reference

{
  "ComplexSchema": {
    "type": "object",
    "properties": {
      "simpleField": {
        "type": "string"
      },
      "referencedField": {
        "$ref": "#/components/schemas/OtherSchema"
      }
    }
  }
}

Nullable Fields

{
  "NullableSchema": {
    "type": "object",
    "properties": {
      "optionalField": {
        "type": "string",
        "nullable": true,
        "description": "Can be null"
      }
    }
  }
}

Additional Properties

{
  "FlexibleSchema": {
    "type": "object",
    "properties": {
      "knownField": {
        "type": "string"
      }
    },
    "additionalProperties": true
  }
}

🎯 Response Codes

Standard Response Codes Used in Dialgen API

Code	Name	Usage
200	OK	Successful GET request
202	Accepted	Async operation accepted (batches)
400	Bad Request	Invalid parameters or body
401	Unauthorized	Missing/invalid API key
402	Payment Required	Insufficient credits
403	Forbidden	Access denied
404	Not Found	Resource not found
409	Conflict	Resource conflict (duplicate call)
500	Internal Server Error	Server error

Response Template

{
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {...}
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "500": {
      "$ref": "#/components/responses/InternalServerError"
    }
  }
}

✅ Validation

Using Swagger Editor

Visit https://editor.swagger.io/
Copy openapi.json contents
Paste into editor
Check for errors in right panel

Using Mint CLI

# Install Mintlify CLI
npm i -g mintlify

# Validate OpenAPI spec
mintlify openapi-check openapi.json

Common Validation Errors

Missing operationId

// ❌ Wrong
{
  "get": {
    "summary": "Get Data"
  }
}

// ✅ Correct
{
  "get": {
    "summary": "Get Data",
    "operationId": "getData"
  }
}

Invalid $ref

// ❌ Wrong
{
  "$ref": "#/components/schemas/NonExistentSchema"
}

// ✅ Correct
{
  "$ref": "#/components/schemas/ExistingSchema"
}

Missing required fields

// ❌ Wrong
{
  "type": "object",
  "required": ["field1"],
  "properties": {
    "field2": {
      "type": "string"
    }
  }
}

// ✅ Correct
{
  "type": "object",
  "required": ["field1"],
  "properties": {
    "field1": {
      "type": "string"
    }
  }
}

🔍 Finding Information

Find all endpoints with a specific tag

Search for "tags": ["TagName"] in the paths section.

Find all schemas

Look in components.schemas section.

Find all error responses

Look in components.responses section.

Find authentication details

Look in components.securitySchemes section.

📝 Best Practices

1. Naming Conventions

operationId: camelCase (e.g., getAgent, createBatch)
Schema names: PascalCase (e.g., Agent, CallStatus)
Properties: camelCase (e.g., agentId, phoneNumber)

2. Descriptions

Always include descriptions for schemas and properties
Use clear, concise language
Include examples where helpful

3. Examples

Provide realistic examples
Include all required fields
Show common use cases

4. Reusability

Use $ref for repeated schemas
Create reusable response templates
Define common parameters once

5. Versioning

Include version in info section
Document breaking changes
Maintain backward compatibility when possible

🚀 Quick Commands

Start development server

cd dialgen-docs
mintlify dev

Validate OpenAPI spec

mintlify openapi-check openapi.json

Format JSON

# Using jq (if installed)
jq . openapi.json > openapi.formatted.json

Search for specific endpoint

# Using grep (Git Bash or WSL)
grep -A 5 "/api/v1/agent" openapi.json

📚 Resources

🎓 Learning Path

Understand OpenAPI basics
- Read OpenAPI specification
- Explore example APIs
Study the Dialgen spec
- Review openapi.json
- Understand schema structure
Make small changes
- Update descriptions
- Add examples
Add new endpoints
- Follow existing patterns
- Validate changes
Advanced features
- Complex schemas
- Custom responses
- Webhooks

💡 Tips

Always validate after making changes
Use consistent formatting (2-space indentation)
Keep examples up to date
Document all required fields
Use meaningful operationIds
Group related endpoints with tags
Reuse schemas when possible
Include error responses for all endpoints

🆘 Troubleshooting

Endpoint not appearing in docs

Check OpenAPI spec is referenced in docs.json
Verify endpoint path in navigation matches OpenAPI
Validate OpenAPI spec for errors
Clear browser cache and restart dev server

Schema not rendering correctly

Check for syntax errors in schema definition
Verify all $ref paths are correct
Ensure required fields exist in properties
Validate with Swagger Editor

Examples not showing

Add example to schema or response
Check JSON syntax is valid
Ensure example matches schema structure

📊 Dialgen API Statistics

Total Endpoints: 11
GET Endpoints: 6
POST Endpoints: 5
Schemas: 20+
Tags: 3 (Agents, Calls, Batches)
Response Codes: 8 (200, 202, 400, 401, 402, 403, 404, 409, 500)

🎯 Summary

This quick reference provides:

✅ Common OpenAPI patterns
✅ Schema examples
✅ Validation methods
✅ Best practices
✅ Troubleshooting tips
✅ Quick commands

Use this guide as a reference when working with the Dialgen OpenAPI specification.

FilesExpand file tree

OPENAPI_QUICK_REFERENCE.md

Latest commit

History