Mintlify Docs

/mintlify-docs [options] <documentation_scope>

/mintlify-docs --api-reference --from-types=src/api/users.ts --with-examples

// src/api/users.ts
/**
 * User management API client
 * @module UserAPI
 */

export interface User {
  /** Unique user identifier */
  id: string;
  /** User's email address */
  email: string;
  /** Display name */
  name: string;
  /** User role */
  role: 'admin' | 'user' | 'guest';
  /** Account creation timestamp */
  createdAt: Date;
}

export interface CreateUserInput {
  email: string;
  name: string;
  password: string;
}

/**
 * Retrieves a user by ID
 * @param userId - The user's unique identifier
 * @returns Promise resolving to the user object
 * @throws {NotFoundError} If user doesn't exist
 * @throws {AuthorizationError} If caller lacks permission
 * @example
 *

*/
export async function getUser(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) throw new Error('Failed to fetch user');
  return response.json();
}

/**
 * Creates a new user
 * @param input - User creation data
 * @returns Promise resolving to the created user
 * @throws {ValidationError} If input is invalid
 * @throws {ConflictError} If email already exists
 * @example
 *

*/
export async function createUser(input: CreateUserInput): Promise<User> {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),
  });
  if (!response.ok) throw new Error('Failed to create user');
  return response.json();
}

---
title: 'User API'
description: 'Manage user accounts and profiles'
icon: 'users'
---

# User Management API

The User API provides endpoints for managing user accounts, authentication, and profiles.

## User Object

The User object represents a user account in your application.

<ResponseField name="id" type="string" required>
  Unique user identifier
</ResponseField>

<ResponseField name="email" type="string" required>
  User's email address
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name
</ResponseField>

<ResponseField name="role" type="'admin' | 'user' | 'guest'" required>
  User role determining access permissions
</ResponseField>

<ResponseField name="createdAt" type="Date" required>
  Account creation timestamp
</ResponseField>

<CodeGroup>

</CodeGroup>

## Get User

<div className="api-method">
  <div className="api-method-label">GET</div>
  <div className="api-method-path">/api/users/:userId</div>
</div>

Retrieves a user by their unique identifier.

### Path Parameters

<ParamField path="userId" type="string" required>
  The user's unique identifier
</ParamField>

### Response

<ResponseField name="user" type="User">
  The requested user object
</ResponseField>

### Error Codes

<ResponseField name="404" type="NotFoundError">
  User with the specified ID doesn't exist
</ResponseField>

<ResponseField name="403" type="AuthorizationError">
  Caller lacks permission to access this user
</ResponseField>

<CodeGroup>

</CodeGroup>

<ResponseExample>

</ResponseExample>

## Create User

<div className="api-method">
  <div className="api-method-label">POST</div>
  <div className="api-method-path">/api/users</div>
</div>

Creates a new user account.

### Request Body

<ParamField body="email" type="string" required>
  User's email address (must be unique)
</ParamField>

<ParamField body="name" type="string" required>
  Display name
</ParamField>

<ParamField body="password" type="string" required>
  Account password (min 8 characters)
</ParamField>

### Response

<ResponseField name="user" type="User">
  The created user object
</ResponseField>

### Error Codes

<ResponseField name="400" type="ValidationError">
  Input validation failed
</ResponseField>

<ResponseField name="409" type="ConflictError">
  Email address already exists
</ResponseField>

<CodeGroup>

</CodeGroup>

<Tip>
  Passwords are automatically hashed using Argon2 before storage. Never log or expose raw passwords.
</Tip>

/mintlify-docs --quickstart --from-code=src/ "Getting started with our authentication system"

---
title: 'Quickstart'
description: 'Get started with authentication in 5 minutes'
icon: 'rocket'
---

# Getting Started

This guide will help you integrate authentication into your application in under 5 minutes.

<Steps>

<Step title="Install the SDK">
  Install the authentication package using your preferred package manager:

  <CodeGroup>

</CodeGroup>
</Step>

<Step title="Configure Environment Variables">
  Add your API credentials to your `.env` file:

<Warning>
    Never commit your `.env` file to version control. Add it to `.gitignore`.
  </Warning>
</Step>

<Step title="Initialize the Client">
  Create an authentication client instance:

</Step>

<Step title="Add Authentication to Your App">
  Wrap your application with the authentication provider:

</Step>

<Step title="Use Authentication Hooks">
  Access authentication state in your components:

</Step>

</Steps>

## Next Steps

<CardGroup cols={2}>

<Card title="API Reference" icon="code" href="/api-reference">
  Explore the complete API documentation
</Card>

<Card title="Authentication Guide" icon="shield" href="/guides/authentication">
  Learn about advanced authentication patterns
</Card>

<Card title="Security Best Practices" icon="lock" href="/guides/security">
  Implement security best practices
</Card>

<Card title="Examples" icon="lightbulb" href="/examples">
  View example implementations
</Card>

</CardGroup>

/mintlify-docs --api-reference --from-openapi=openapi.yaml

{
  "$schema": "https://mintlify.com/schema.json",
  "name": "Your API Documentation",
  "logo": {
    "dark": "/logo/dark.svg",
    "light": "/logo/light.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },
  "topbarLinks": [
    {
      "name": "Support",
      "url": "mailto:support@example.com"
    }
  ],
  "topbarCtaButton": {
    "name": "Dashboard",
    "url": "https://dashboard.example.com"
  },
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference"
    },
    {
      "name": "Guides",
      "url": "guides"
    }
  ],
  "anchors": [
    {
      "name": "Documentation",
      "icon": "book-open-cover",
      "url": "https://docs.example.com"
    },
    {
      "name": "Community",
      "icon": "discord",
      "url": "https://discord.gg/example"
    },
    {
      "name": "GitHub",
      "icon": "github",
      "url": "https://github.com/example/repo"
    }
  ],
  "navigation": [
    {
      "group": "Get Started",
      "pages": [
        "introduction",
        "quickstart",
        "development"
      ]
    },
    {
      "group": "API Reference",
      "pages": [
        "api-reference/authentication",
        "api-reference/users",
        "api-reference/organizations"
      ]
    }
  ],
  "footerSocials": {
    "twitter": "https://twitter.com/example",
    "github": "https://github.com/example",
    "linkedin": "https://www.linkedin.com/company/example"
  },
  "analytics": {
    "posthog": {
      "apiKey": "phc_xxx"
    }
  },
  "api": {
    "baseUrl": "https://api.example.com",
    "auth": {
      "method": "bearer"
    }
  }
}

<Accordion title="How does authentication work?">
  Our authentication system uses JWT tokens with automatic refresh. Sessions last 7 days by default.
</Accordion>

<Info>
  All API requests must include a valid Bearer token in the Authorization header.
</Info>

<Warning>
  Never expose your API secret key in client-side code.
</Warning>

<Tip>
  Use environment variables to manage different API keys for development and production.
</Tip>

<Check>
  Your API credentials are correctly configured!
</Check>