### Mintlify Navigation Example (json)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/docs

Example of a navigation structure for `mint.json`, organizing documentation pages into groups.

```json
{
  "group": "Users",
  "pages": [
    "api/users/get-user",
    "api/users/get-all-users",
    "api/users/search-users",
    "api/users/create-user"
  ]
}
```

--------------------------------

### GET /spells/get-all/

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Retrieves a list of all available spells.

```APIDOC
## GET /spells/get-all/

### Description
Retrieves a list of all spells available in the system.

### Method
GET

### Endpoint
/spells/get-all/

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **list[Spell]** - A list of spell objects.

#### Response Example
```json
[
  {
    "id": "fireball",
    "name": "Fireball",
    "description": "A básica spell that shoots a ball of fire."
  },
  {
    "id": "ice_shard",
    "name": "Ice Shard",
    "description": "Launches a shard of ice at the target."
  }
]
```
```

--------------------------------

### Mintlify Configuration Example (json)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/docs

Example snippet showing how to include the OpenAPI schema URL in the `mint.json` configuration for automatic API documentation generation.

```json
{
  ...
  "openapi":"https://next-fast-turbo-api.vercel.app/openapi.json"
  ...
}
```

--------------------------------

### Install Project Dependencies

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

After cloning the repository, navigate into the project directory and install all necessary dependencies using pnpm. This command ensures all packages required for the monorepo are downloaded and linked.

```bash
cd app-name
pnpm install
```

--------------------------------

### Install Python Dependencies using pip

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

If not using Poetry, this command installs the Python dependencies listed in the 'requirements.txt' file using pip. Ensure the virtual environment is activated before running this command.

```bash
pip install -r requirements.txt
```

--------------------------------

### Create Python Virtual Environment with Poetry

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

This command uses Poetry to create and install dependencies within a virtual environment for the Python API. It's the recommended method for managing Python dependencies in this project. Ensure Poetry is installed globally.

```bash
poetry install
```

--------------------------------

### Clone Next-Fast-Turbo Repository

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

This command clones the Next-Fast-Turbo repository from GitHub to your local machine. Ensure you have Git installed. The cloned repository will be placed in a directory named 'app-name'.

```bash
git clone https://github.com/cording12/next-fast-turbo.git app-name
```

--------------------------------

### GET /spells/search/

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Searches for spells based on a keyword and returns matching results.

```APIDOC
## GET /spells/search/

### Description
Searches for spells that match a given keyword in either their name or description. Returns a paginated list of results.

### Method
GET

### Endpoint
/spells/search/

### Parameters
#### Query Parameters
- **keyword** (str, optional) - The keyword to search for within spell names or descriptions. Defaults to None.
- **max_results** (int, optional) - The maximum number of spells to return in the search results. Defaults to 10.
- **search_on** (Literal["spells", "description"], optional) - The field to perform the search on. Can be 'spells' (for name) or 'description'. Defaults to 'spells'.

### Response
#### Success Response (200)
- **SpellSearchResults** (SpellSearchResults) - An object containing a list of spells that match the search criteria.
  - **results** (list[Spell]) - A list of Spell objects.

#### Response Example
```json
{
  "results": [
    {
      "id": "fireball",
      "name": "Fireball",
      "description": "A básica spell that shoots a ball of fire."
    }
  ]
}
```

#### Error Response (404)
- **detail** (str) - "No spells found matching the search criteria."
```

--------------------------------

### Create Spell CRUD Operations in Python

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Defines a CRUD class for the 'Spell' model, inheriting from a base CRUD class. It includes methods for getting a single spell, fetching all spells, and searching spells, with error handling for API exceptions. This setup utilizes Supabase for asynchronous database operations.

```python
from fastapi import HTTPException
from supabase_py_async import AsyncClient

from src.crud.base import CRUDBase
from src.schemas import Spell, SpellCreate, SpellUpdate


class CRUDSpell(CRUDBase[Spell, SpellCreate, SpellUpdate]):
    async def get(self, db: AsyncClient, *, id: str) -> Spell | None:
        try:
            return await super().get(db, id=id)
        except Exception as e:
            raise HTTPException(
                status_code=404,
                detail=f"{e.code}: Spell not found. {e.details}",
            )

    async def get_all(self, db: AsyncClient) -> list[Spell]:
        try:
            return await super().get_all(db)
        except Exception as e:
            raise HTTPException(
                status_code=404,
                detail=f"An error occurred while fetching spells. {e}",
            )

    async def search_all(
        self, db: AsyncClient, *, field: str, search_value: str, max_results: int
    ) -> list[Spell]:
        try:
            return await super().search_all(
                db, field=field, search_value=search_value, max_results=max_results
            )
        except Exception as e:
            raise HTTPException(
                status_code=404,
                detail=f"An error occurred while searching for spells. {e}",
            )


spell = CRUDSpell(Spell)
```

--------------------------------

### Initialize Schemas in __init__.py (Python)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Aggregates schema definitions from various modules into a central `__init__.py` file for simplified import paths. Facilitates easy access to `Spell` and `User` related models across the application.

```python
from .user import User, UserCreate, UserSearchResults, UserUpdate
from .spell import Spell, SpellCreate, SpellSearchResults, SpellUpdate

```

--------------------------------

### GET /spells/get/

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Retrieves a specific spell using its unique ID.

```APIDOC
## GET /spells/get/

### Description
Retrieves a specific spell from the database using its unique spell ID.

### Method
GET

### Endpoint
/spells/get/

### Parameters
#### Query Parameters
- **spell_id** (str) - Required - The unique identifier of the spell to retrieve.

### Response
#### Success Response (200)
- **spell** (Spell) - An object containing the details of the spell.

#### Response Example
```json
{
  "id": "fireball",
  "name": "Fireball",
  "description": "A básica spell that shoots a ball of fire."
}
```
```

--------------------------------

### Navigate to Python API Directory

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

This command changes the current directory to the 'api' folder, which contains the Python backend code. This is necessary for running Python-specific setup and development commands.

```bash
cd apps/api
```

--------------------------------

### Include Spell API Router in FastAPI Application

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Integrates the newly created spell API endpoints into the main FastAPI application router. This involves importing the `spells` router and including it with a specific prefix and tags. This ensures that the spell-related API routes are accessible under the `/spells` path.

```python
from fastapi import APIRouter
from src.api.api_v1.endpoints import users, spells

api_router = APIRouter()
api_router.include_router(users.router, prefix="/users", tags=["users"], responses={404: {"description": "Not found"}})
api_router.include_router(spells.router, prefix="/spells", tags=["spells"], responses={404: {"description": "Not found"}})

```

--------------------------------

### Create Spell Schemas with Pydantic (Python)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Defines Pydantic models for spells, including base schema, creation, update, and search result structures. Ensures data integrity and compatibility with Supabase tables.

```python
from typing import ClassVar, Sequence

from pydantic import BaseModel


class Spell(BaseModel):
    id: str
    name: str
    description: str
    table_name: ClassVar[str] = "spells"


class SpellCreate(BaseModel):
    id: str
    name: str
    description: str


class SpellUpdate(BaseModel):
    id: str
    name: str
    description: str


class SpellSearchResults(BaseModel):
    results: Sequence[Spell]

```

--------------------------------

### Use Generated API Service (TypeScript)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/nextjs

Demonstrates how to import and use a generated API service client, such as UsersService, to make requests to your backend. It includes an example of calling a user search function with parameters.

```TypeScript
import { UsersService } from "@/lib/api/client";

const response = await UsersService.usersSearchUsers({
        keyword: "keyword",
        searchOn: "searchOn",
        maxResults: "maxResults",
      });
```

--------------------------------

### Add Spell CRUD to Project Initialization in Python

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

This Python code snippet demonstrates how to import and expose the 'spell' CRUD instance by adding it to the __init__.py file within the 'src/crud' directory. This makes the 'spell' object available for use throughout the application, similar to how other model instances like 'user' are exposed.

```python
from .crud_user import user
from .crud_spell import spell
```

--------------------------------

### Create Spell API Endpoints in Python

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Defines the API endpoints for spell management using FastAPI. It includes routes for retrieving a spell by ID, fetching all spells, and searching spells by keyword. This code relies on FastAPI, database dependencies (SessionDep), and CRUD operations defined in `src.crud.spell` and Pydantic schemas from `src.schemas`.

```python
from typing import Literal, Optional, Union

from fastapi import APIRouter, HTTPException

from src.api.deps import SessionDep
from src.crud import spell
from src.schemas import Spell, SpellSearchResults

router = APIRouter()


@router.get("/get/", status_code=200, response_model=Spell)
async def get_spell(session: SessionDep, spell_id: str) -> Spell:
    """Returns a spell from a spell_id.

    **Returns:**
    - spell: spell object.
    """
    return await spell.get(session, id=spell_id)


@router.get("/get-all/", status_code=200, response_model=list[Spell])
async def get_all_spells(session: SessionDep) -> list[Spell]:
    """Returns a list of all spells.

    **Returns:**
    - list[spell]: List of all spells.
    """
    return await spell.get_all(session)


@router.get("/search/", status_code=200, response_model=SpellSearchResults)
async def search_spells(
    session: SessionDep,
    search_on: Literal["spells", "description"] = "spell",
    keyword: Optional[Union[str, int]] = None,
    max_results: Optional[int] = 10,
) -> SpellSearchResults:
    """
    Search for spells based on a keyword and return the top `max_results` spells.

    **Args:**
    - keyword (str, optional): The keyword to search for. Defaults to None.
    - max_results (int, optional): The maximum number of search results to return. Defaults to 10.
    - search_on (str, optional): The field to perform the search on. Defaults to "email".

    **Returns:**
    - SpellSearchResults: Object containing a list of the top `max_results` spells that match the keyword.
    """
    if not keyword:
        results = await spell.get_all(session)
        return SpellSearchResults(results=results)

    results = await spell.search_all(
        session, field=search_on, search_value=keyword, max_results=max_results
    )

    if not results:
        raise HTTPException(
            status_code=404, detail="No spells found matching the search criteria"
        )

    return SpellSearchResults(results=results)

```

--------------------------------

### Create Python Virtual Environment with venv

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

This command uses Python's built-in `venv` module to create a virtual environment named '.venv' in the current directory. This isolates project dependencies from the global Python installation.

```bash
python -m venv .venv
```

--------------------------------

### Form Submission with API Call (TypeScript)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/nextjs

An example of an onSubmit handler for a form that uses the generated API client to search for users. It parses form data, calls the UsersService, and handles the response or potential errors.

```TypeScript
  const onSubmit = async (data: z.infer<typeof FormSchema>) => {
    try {
      const maxResults = data.searchResults ? parseInt(data.searchResults) : 10;
      const response = await UsersService.usersSearchUsers({
        keyword: data.keyword,
        searchOn: data.searchOn,
        maxResults: maxResults,
      });
      setSearchResults(response);
      setError(null);
    } catch (error) {
      setSearchResults({ results: [] });
      setError(error);
    }
  };

```

--------------------------------

### Turbo.json Configuration with globalEnv

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/turbo

Example of a `turbo.json` file with the `globalEnv` key added. This configuration is used to specify environment variables that should be globally available to all tasks within the monorepo, preventing ESLint errors related to `.env` file references.

```json
{
  "globalEnv": [
    "NODE_ENV"
  ]
}
```

--------------------------------

### Python Pydantic Schema Definition

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/fastapi

Defines a Pydantic model for a 'Spell' object. This schema includes fields for `id`, `name`, and `description`, and a class variable `table_name` to specify the corresponding database table. This is used to validate data and map objects to database entities.

```python
from pydantic import BaseModel
from typing import ClassVar

class Spell(BaseModel):
    id: str
    name: str
    description: str
    table_name: ClassVar[str] = "spells"
```

--------------------------------

### Run Dev Docs Site (pnpm)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/docs

Command to run the documentation site locally. Requires pnpm package manager and execution within the 'docs' directory.

```bash
pnpm run dev
```

--------------------------------

### Initialize Turbo Project with npm, yarn, or pnpm

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/turbo

Commands to create a new Turbo monorepo project using different package managers. This is the initial step for setting up the project structure.

```bash
npx create-turbo@latest
```

```bash
yarn dlx create-turbo@latest
```

```bash
pnpm dlx create-turbo@latest
```

--------------------------------

### Generating API Endpoint Documentation

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/docs

This section details the process of generating API endpoint documentation using FastAPI's OpenAPI support and Mintlify's `@mintlify/scraping` package. It covers generating MDX files and updating the `mint.json` configuration.

```APIDOC
## Generating OpenAPI Schema

### Step 1: Generate MDX

Run the `generate-api` scripts within the `package.json` to generate the required MDX files. There are two scripts here, one configured to use the production `OpenAPI.json` and the second configured to use the development version. It is typically preferred to use the production version once any changes to your API have been made and published.

### Step 2: Update mint.json

#### Add new MDX files to navigation

Upon generating the relevant API information, `@mintlify/scraping` helpfully outputs the suggested navigation to the terminal:

```bash
navigation object suggestion:
[
  {
    "group": "users",
    "pages": [
      "api/users/get-user",
      "api/users/get-all-users",
      "api/users/search-users",
      "api/users/create-user"
    ]
  },
  {
    "group": "spells",
    "pages": [
      "api/spells/get-spell",
      "api/spells/get-all-spells",
      "api/spells/search-spells"
    ]
  }
]
```

Copy this navigation object suggestion and add it your `mint.json` under the `navigation` object:

```json
"navigation": [
  {
    "group": "Getting Started",
    "pages": ["documentation/introduction", "documentation/local-development"]
  },
  {
    "group": "Configuration",
    "pages": [
      "documentation/configuration/turbo",
      "documentation/configuration/fastapi",
      "documentation/configuration/nextjs",
      "documentation/configuration/docs"
    ]
  },
  {
    "group": "Deployment",
    "pages": [
      "documentation/deployment/vercel",
      "documentation/deployment/deployment"
    ]
  },
  {
    "group": "API Reference",
    "pages": ["api/introduction"]
  },
  {
    "group": "Users",
    "pages": [
      "api/users/get-user",
      "api/users/get-all-users",
      "api/users/search-users",
      "api/users/create-user"
    ]
  },
  {
    "group": "Spells",
    "pages": [
      "api/spells/get-spell",
      "api/spells/get-all-spells",
      "api/spells/search-spells"
    ]
  }
],
```

#### Add OpenAPI endpoint to `mint.json`

Add the `openapi` key to your `mint.json`. This, preferably, can be linked to your published OpenAPI schema:

```json
{
  ...  
  "openapi":"https://next-fast-turbo-api.vercel.app/openapi.json"
  ...
}
```

This enables the generated MDX files to describe and interact with your API.

**Warning:** If this does not auto-populate your API reference with the documentation, the solution is to manually create an `openapi.json` file in the `docs` root and copy/paste your `openapi.json` into this file.
```

--------------------------------

### Configure Python API Environment Variables

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

This snippet shows the structure of the `.env` file for the Python API. It defines essential environment variables for database connection and API keys. Replace placeholder values with actual credentials.

```env
DB_URL=supabase_url
DB_API_KEY=supabase_api_key
DB_EMAIl=email_address
DB_PASSWORD=password
```

--------------------------------

### Compound Launch Configuration (JSON)

Source: https://next-fast-turbo.mintlify.app/documentation/local-development

Defines a compound launch configuration within a VS Code workspace file. This allows launching multiple individual debug configurations simultaneously. It references existing configurations by name to create a combined debugging session.

```json
{
  "launch": {
    "version": "0.2.0",
    "configurations": [],
    "compounds": [
      {
        "name": "Launch Frontend and Backend",
        "configurations": ["Next.js: Chrome", "Python: FastAPI"]
      }
    ]
  }
}
```

--------------------------------

### Initialize API Configuration (OpenAPI.ts)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/nextjs

Shows the default structure of the OpenAPI configuration file generated by the client generation tool. This file contains settings like BASE URL, API version, and authentication details.

```TypeScript
export const OpenAPI: OpenAPIConfig = {
  BASE: "http://127.0.0.0:8000",
  VERSION: "0.1.0",
  WITH_CREDENTIALS: false,
  CREDENTIALS: "include",
  TOKEN: undefined,
  USERNAME: undefined,
  PASSWORD: undefined,
  HEADERS: undefined,
  ENCODE_PATH: undefined,
};
```

--------------------------------

### Configure and Run API Client Generation (package.json)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/nextjs

Defines scripts in package.json to generate a TypeScript API client from an OpenAPI schema. Supports both production and local development URLs. Ensure the OpenAPI URL is correctly configured.

```JSON
{
  "scripts": {
    ...
    "generate-client": "openapi --input https://next-fast-turbo.vercel.app/openapi.json --output ./lib/api/client --client axios --useOptions --useUnionTypes",
    "generate-client:dev": "openapi --input http://127.0.0.0:8000/openapi.json --output ./lib/api/client --client axios --useOptions --useUnionTypes"
    ...
  }
}
```

--------------------------------

### Typing API Search Results (TypeScript)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/nextjs

Illustrates how to import and use generated TypeScript types, like UserSearchResults, to correctly type state variables when handling API responses. This improves type safety in your application.

```TypeScript
import { UsersService, UserSearchResults } from "@/lib/api/client";

const [searchResults, setSearchResults] = React.useState<UserSearchResults>({
    results: [],
  });

```

--------------------------------

### Update Root Layout for API Base URL (layout.tsx)

Source: https://next-fast-turbo.mintlify.app/documentation/configuration/nextjs

Overrides the default API base URL in the generated OpenAPI configuration based on the Node environment. This ensures the correct API endpoint is used in production versus development.

```TypeScript
import { OpenAPI } from "@/lib/api/client";

if (process.env.NODE_ENV === "production") {
  OpenAPI.BASE = "https://next-fast-turbo.vercel.app"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.