Skip to main content

​
Welcome Contributors

This guide helps Sendsational team members write high-quality documentation for our game APIs. Our docs are built with Mintlify and use OpenAPI specifications for auto-generation.

​
Documentation Structure

docs/
├── docs.json                 # Configuration
├── games/                    # Game project documentation
│   └── wheel/               # Wheel game
│       ├── introduction.mdx # API overview
│       └── quickstart.mdx   # Getting started
└── openapi/                 # OpenAPI specifications
    └── wheel.json           # Wheel API spec

​
Adding a New Game

1

Create OpenAPI Specification

Create a new OpenAPI 3.0 spec in openapi/your-game.json:
{
  "openapi": "3.0.0",
  "info": {
    "title": "Your Game API",
    "version": "1.0.0"
  },
  "paths": {
    // Define your endpoints
  }
}
See openapi/README.md for detailed guidance.
2

Create Documentation Pages

Create a new directory in games/your-game/ with:
  • introduction.mdx - API overview, authentication, base URL
  • quickstart.mdx - Getting started examples
Copy from games/wheel/ as templates.
3

Update Navigation

Add your game to docs.json navigation:
{
  "tab": "Games",
  "groups": [
    {
      "group": "Your Game",
      "pages": [
        "games/your-game/introduction",
        "games/your-game/quickstart"
      ]
    },
    {
      "group": "Your Game - Endpoints",
      "pages": [
        "GET /games/your-game/resource",
        "POST /games/your-game/resource"
      ]
    }
  ]
}
4

Preview & Deploy

Preview locally:
cd docs
mintlify dev
Then commit and push to deploy.

​
Writing Guidelines

​
Use Clear Language

✅ Good

“Create a new player profile with authentication credentials”

❌ Avoid

“Utilize the profile creation endpoint to instantiate user entities”

​
Include Code Examples

Always provide runnable code examples in multiple languages: 
curl -X POST https://api.sstxt.us/v5/games/wheel/profiles \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "player1"}'

​
Document Errors

Always document common error scenarios:
Invalid or missing API key
{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}
Resource doesn’t exist
Too many requests

​
Mintlify Components

​
Callouts

Use Note for helpful information that supports the main content
Use Tip for best practices and expert advice
Use Warning for important cautions or potential issues

​
Code Blocks

Use syntax highlighting and specify the language: 
const config = {
  baseURL: 'https://api.sstxt.us/v5',
  timeout: 5000
};

​
Interactive Steps

Use Steps for sequential instructions:
1

First Step

Do this first
2

Second Step

Then do this

​
Cards for Navigation

Wheel API

Wheel game documentation

OpenAPI Guide

Learn about OpenAPI specs

​
OpenAPI Best Practices

​
Complete Schemas

Always define complete request and response schemas: 
{
  "schemas": {
    "Profile": {
      "type": "object",
      "required": ["username", "email"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier",
          "example": "prof_123456"
        },
        "username": {
          "type": "string",
          "example": "player1"
        }
      }
    }
  }
}

​
Use References

Reuse common components with $ref: 
{
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Profile"
          }
        }
      }
    }
  }
}

​
Document All Parameters

Every parameter needs a description and example: 
{
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Profile identifier",
      "schema": {
        "type": "string"
      },
      "example": "prof_123456"
    }
  ]
}

​
Testing Documentation

​
Preview Locally

cd docs
mintlify dev
Open http://localhost:3000 to preview changes. Verify all internal links work:
  • ✅ /games/wheel/introduction
  • ❌ /api-reference (old, removed)

​
Validate OpenAPI

npm install -g @stoplight/spectral-cli
spectral lint openapi/wheel.json

​
Cursor Integration

We use Cursor rules for consistent documentation. The rules are automatically applied when editing .mdx files in the docs folder. Location: .cursor/rules/mintlify-technical-writing.mdc The rules provide:
  • Technical writing best practices
  • Mintlify component examples
  • Content quality standards
  • Accessibility requirements

​
Getting Help

Mintlify Docs

Official Mintlify documentation

Internal Support

Contact the internal support team

GitHub Issues

Report bugs or request features

OpenAPI Spec

OpenAPI 3.0 specification

​
Common Patterns

​
API Endpoint Documentation

Each endpoint should include:
  • Description
  • Authentication requirements
  • Request parameters
  • Request body schema
  • Success response examples
  • Error response examples
  • Rate limiting info

​
Quick Start Pages

Include:
  • Prerequisites
  • Authentication setup
  • First API call example
  • Common operations
  • Error handling
  • Next steps

​
Introduction Pages

Cover:
  • Overview and purpose
  • Base URL
  • Authentication method
  • Core resources
  • API structure
  • Response format
  • Rate limiting

​
Style Guide

  • Use second person (“you”) for instructions
  • Use active voice over passive voice
  • Keep sentences concise
  • Use present tense
  • Include code examples for all API calls
  • Test all code before publishing
  • Update docs when API changes