Source File Annotations

Overview

pb-ext uses three source file directives to control API documentation generation:

Directive	Location	Purpose	Required
`// API_SOURCE`	Top of `.go` file	Marks file for AST parsing	Yes (for handler files)
`// API_DESC <text>`	Function doc comment	Sets OpenAPI description	No (auto-generated fallback)
`// API_TAGS <csv>`	Function doc comment	Sets OpenAPI tags	No (auto-generated from path)

Directives are comment lines — they don’t affect runtime behavior, only documentation generation.

`// API_SOURCE` — File Marker

Purpose

Marks a Go file for AST parsing. Only files with this directive are analyzed for handler functions. Type definitions (structs) in imported packages are discovered automatically.

Placement

Place at the top of the file, before the package declaration or imports:

// API_SOURCE
package main

import (
    "net/http"
    "github.com/pocketbase/pocketbase/core"
)

func myHandler(c *core.RequestEvent) error {
    return c.JSON(http.StatusOK, map[string]any{"status": "ok"})
}

// API_SOURCE

package main

import "github.com/pocketbase/pocketbase/core"

package main

// API_SOURCE  ❌ Too late, parser already skipped this file

import "github.com/pocketbase/pocketbase/core"

When to Use

Mark these files:

Handler files (handlers.go, routes.go, api.go)
Files containing func(c *core.RequestEvent) error functions

Don’t mark these files:

Type definition files (types.go, models.go) — auto-discovered via imports
Utility files without handlers (helpers.go, utils.go)
Test files (*_test.go)

Example: handlers.go

// API_SOURCE
package main

import (
    "encoding/json"
    "net/http"
    "github.com/pocketbase/pocketbase/core"
)

// API_DESC Create a new todo item
// API_TAGS Todos
func createTodoHandler(c *core.RequestEvent) error {
    var req TodoRequest
    if err := json.NewDecoder(c.Request.Body).Decode(&req); err != nil {
        return c.JSON(http.StatusBadRequest, map[string]any{"error": "Invalid JSON"})
    }
    // ...
}

// API_DESC Get all todos with optional filtering
// API_TAGS Todos
func getTodosHandler(c *core.RequestEvent) error {
    // ...
}

`// API_DESC` — Handler Description

Purpose

Sets the description field in the OpenAPI operation. This appears in Swagger UI and helps developers understand what the endpoint does.

Placement

Place in the function’s doc comment (the comment block directly above the function):

// API_DESC Get all todos with optional filtering by completion status and priority
func getTodosHandler(c *core.RequestEvent) error {
    // ...
}

Fallback Behavior

If omitted, the system auto-generates a description from the handler name:

Handler Name	Auto-Generated Description
`getTodosHandler`	Get Todos
`createTodoHandler`	Create Todo
`updateTodoHandler`	Update Todo
`deleteTodoHandler`	Delete Todo
`listUsersHandler`	List Users

Auto-generated descriptions are basic. Always add // API_DESC for better documentation.

Writing Good Descriptions

Start with a verb

Get, Create, Update, Delete, List, Search, Calculate, etc.

Explain the purpose

What does this endpoint do? What data does it return?

Mention key features

Filtering, pagination, optional parameters, special behavior.

Keep it concise

1-2 sentences. Save detailed docs for external documentation.

// API_DESC Handler
func getTodosHandler(c *core.RequestEvent) error {
    // Too vague, doesn't explain what it does
}

// API_DESC Get all todos
func getTodosHandler(c *core.RequestEvent) error {
    // Clear and concise
}

// API_DESC Get all todos with optional filtering by completion status and priority
func getTodosHandler(c *core.RequestEvent) error {
    // Mentions key features (filtering, query params)
}

`// API_TAGS` — OpenAPI Tags

Purpose

Groups related endpoints in Swagger UI. Tags appear as collapsible sections in the navigation sidebar.

Placement

Place in the function’s doc comment, same as // API_DESC:

// API_DESC Create a new todo item
// API_TAGS Todos, Management
func createTodoHandler(c *core.RequestEvent) error {
    // ...
}

Format

Comma-separated list of tag names:

// Single tag
// API_TAGS Todos

// Multiple tags
// API_TAGS Todos, Management, Public

Fallback Behavior

If omitted, the system auto-generates a tag from the path:

Path	Auto-Generated Tag
`/api/v1/todos`	`Todos`
`/api/v1/users/{id}`	`Users`
`/api/v1/admin/stats`	`Admin`

Best Practices

Organize by Feature

// User management endpoints
// API_TAGS Users
func listUsersHandler(c *core.RequestEvent) error { /* ... */ }

// API_TAGS Users
func getUserHandler(c *core.RequestEvent) error { /* ... */ }

// API_TAGS Users
func createUserHandler(c *core.RequestEvent) error { /* ... */ }

This groups all user-related endpoints under a single “Users” tag in Swagger UI.

Use Multiple Tags for Cross-Cutting Features

// API_DESC Get current server time
// API_TAGS Utility, Public
func timeHandler(c *core.RequestEvent) error { /* ... */ }

// API_DESC Health check endpoint
// API_TAGS Utility, Monitoring
func healthHandler(c *core.RequestEvent) error { /* ... */ }

Endpoints appear in multiple tag groups.

Consistency Matters

// ❌ Inconsistent capitalization
// API_TAGS todos
// API_TAGS Todos
// API_TAGS TODO

// ✅ Consistent
// API_TAGS Todos
// API_TAGS Todos
// API_TAGS Todos

Indirect Parameter Detection

What Requires Annotations?

Nothing. Indirect parameter detection is fully automatic for helper functions that accept *core.RequestEvent as the first parameter.

How It Works

The parser automatically extracts parameters from helper functions:

func parseTimeParams(e *core.RequestEvent) timeParams {
    q := e.Request.URL.Query()
    return timeParams{
        Interval: q.Get("interval"),
        From:     q.Get("from"),
        To:       q.Get("to"),
    }
}

func getDataHandler(e *core.RequestEvent) error {
    params := parseTimeParams(e)
    // No annotation needed — params auto-detected: interval, from, to
}

func parseIntParam(e *core.RequestEvent, name string, def int) int {
    val := e.Request.URL.Query().Get(name)
    if val == "" {
        return def
    }
    i, _ := strconv.Atoi(val)
    return i
}

func listItemsHandler(e *core.RequestEvent) error {
    page := parseIntParam(e, "page", 1)    // Param name extracted: "page"
    limit := parseIntParam(e, "limit", 10) // Param name extracted: "limit"
    // No annotation needed — parser reads string literals
}

Requirements for Auto-Detection

Helper must accept *core.RequestEvent first

func parseTimeParams(e *core.RequestEvent) timeParams { /* ... */ }

Helper must NOT return error

// ✅ Detected as helper
func parseTimeParams(e *core.RequestEvent) timeParams { /* ... */ }

// ❌ Detected as handler, not analyzed for params
func parseTimeParams(e *core.RequestEvent) error { /* ... */ }

Generic helpers need string literal param names

// ✅ Param name extracted: "page"
page := parseIntParam(e, "page", 1)

// ❌ Param name not extracted (variable, not literal)
paramName := "page"
page := parseIntParam(e, paramName, 1)

When Annotations Are Needed vs Auto-Detected

Feature	Auto-Detected	Annotation Needed
Request body	✅ `c.BindBody(&req)`, `json.Decode(&req)`	❌
Response schema	✅ `c.JSON(status, data)`	❌
Query parameters	✅ `c.Request.URL.Query().Get("name")`	❌
Header parameters	✅ `c.Request.Header.Get("name")`	❌
Path parameters	✅ `c.Request.PathValue("id")`	❌
Indirect params (helpers)	✅ Helper accepts `*core.RequestEvent`	❌
Handler description	⚠️ Fallback: handler name	✅ `// API_DESC`
Endpoint tags	⚠️ Fallback: path-based	✅ `// API_TAGS`
File inclusion	❌ Not parsed by default	✅ `// API_SOURCE`

In most cases, only // API_SOURCE is required. The other directives (// API_DESC, // API_TAGS) are optional but recommended for better documentation.

Real Annotated Examples from handlers.go

createTodoHandler (Full Example)

// API_DESC Create a new todo item
// API_TAGS Todos
func createTodoHandler(c *core.RequestEvent) error {
    // Auth check (auto-detected)
    if c.Auth == nil {
        return c.JSON(http.StatusUnauthorized, map[string]any{"error": "Authentication required"})
    }

    // Request body (auto-detected)
    var req TodoRequest
    if err := json.NewDecoder(c.Request.Body).Decode(&req); err != nil {
        return c.JSON(http.StatusBadRequest, map[string]any{"error": "Invalid JSON payload"})
    }

    // Response (auto-detected)
    return c.JSON(http.StatusCreated, map[string]any{
        "message": "Todo created successfully! ✅",
        "todo": map[string]any{
            "id":    record.Id,
            "title": record.GetString("title"),
        },
    })
}

What’s detected:

Description: “Create a new todo item” (from // API_DESC)
Tags: [“Todos”] (from // API_TAGS)
Auth: Required (from if c.Auth == nil check)
Request: TodoRequest schema (from json.Decode(&req))
Response: Inline object schema with message and todo properties

getTodosHandler (With Query Params)

// API_DESC Get all todos with optional filtering
// API_TAGS Todos
func getTodosHandler(c *core.RequestEvent) error {
    // Query params (auto-detected)
    completed := c.Request.URL.Query().Get("completed")
    priority := c.Request.URL.Query().Get("priority")

    // Response (auto-detected)
    return c.JSON(http.StatusOK, map[string]any{
        "todos": todos,
        "count": len(todos),
        "filters": map[string]any{
            "completed": completed,
            "priority":  priority,
        },
    })
}

What’s detected:

Description: “Get all todos with optional filtering”
Tags: [“Todos”]
Query params: completed, priority (both optional, type: string)
Response: Inline object with todos, count, filters properties

getTodoHandler (With Path Param)

// API_DESC Get a specific todo by ID
// API_TAGS Todos
func getTodoHandler(c *core.RequestEvent) error {
    // Path param (auto-detected, required=true)
    todoID := c.Request.PathValue("id")

    // Response (auto-detected)
    return c.JSON(http.StatusOK, map[string]any{
        "message": "Todo retrieved successfully 📖",
        "todo": map[string]any{
            "id":    record.Id,
            "title": record.GetString("title"),
        },
    })
}

What’s detected:

Description: “Get a specific todo by ID”
Tags: [“Todos”]
Path param: id (required=true, type: string)
Response: Inline object with message and todo properties

Best Practices Summary

Mark handler files with // API_SOURCE

Place at the top of the file, before package declaration.

Add // API_DESC to all handlers

Don’t rely on auto-generated descriptions — write clear, concise explanations.

Use // API_TAGS for grouping

Consistent tag names improve Swagger UI navigation.

Extract parameter parsing into helpers

Domain helpers make code cleaner and params are still auto-detected.

Verify with the debug endpoint

Check /api/docs/debug/ast to confirm all metadata is detected.

Debugging Missing Metadata

If a parameter, schema, or description is missing from the OpenAPI spec:

1. Check the debug endpoint

curl -H "Authorization: Bearer YOUR_SUPERUSER_TOKEN" \
     http://localhost:8090/api/docs/debug/ast

Look for your handler in the handlers section. If it’s missing:

File doesn’t have // API_SOURCE
Function signature doesn’t match func(c *core.RequestEvent) error

2. Verify helper function signatures

For indirect parameter detection:

Helper must accept *core.RequestEvent as first parameter
Helper must NOT return error (that makes it a handler)
Generic helpers need string literal param names at call site

3. Check directive placement

// API_SOURCE must be at the top of the file
// API_DESC and // API_TAGS must be in the function doc comment (directly above the function)

4. Review AST parser logs

Look for parse errors in server logs:

api docs: failed to parse API_SOURCE file file=cmd/server/handlers.go err=...

Common causes: syntax errors, import issues, circular dependencies.

Next Steps

OpenAPI System

Deep dive into AST parsing internals

Route Registration

Learn manual and CRUD registration patterns

Getting Started

Core Concepts

API Documentation

Features

Advanced

CLI Tools

Deployment

Source File Annotations

Overview

`// API_SOURCE` — File Marker

Purpose

Placement

When to Use

`// API_DESC` — Handler Description

Purpose

Placement

Fallback Behavior

Writing Good Descriptions

`// API_TAGS` — OpenAPI Tags

Purpose

Placement

Format

Fallback Behavior

Best Practices

Indirect Parameter Detection

What Requires Annotations?

How It Works

Requirements for Auto-Detection

When Annotations Are Needed vs Auto-Detected

Real Annotated Examples from handlers.go

Best Practices Summary

Debugging Missing Metadata

Next Steps

OpenAPI System

Route Registration

​Overview

​// API_SOURCE — File Marker

​Purpose

​Placement

​When to Use

​// API_DESC — Handler Description

​Purpose

​Placement

​Fallback Behavior

​Writing Good Descriptions

​// API_TAGS — OpenAPI Tags

​Purpose

​Placement

​Format

​Fallback Behavior

​Best Practices

​Indirect Parameter Detection

​What Requires Annotations?

​How It Works

​Requirements for Auto-Detection

​When Annotations Are Needed vs Auto-Detected

​Real Annotated Examples from handlers.go

​Best Practices Summary

​Debugging Missing Metadata

​Next Steps

OpenAPI System

Route Registration

Overview

`// API_SOURCE` — File Marker

Purpose

Placement

When to Use

`// API_DESC` — Handler Description

Purpose

Placement

Fallback Behavior

Writing Good Descriptions

`// API_TAGS` — OpenAPI Tags

Purpose

Placement

Format

Fallback Behavior

Best Practices

Indirect Parameter Detection

What Requires Annotations?

How It Works

Requirements for Auto-Detection

When Annotations Are Needed vs Auto-Detected

Real Annotated Examples from handlers.go

Best Practices Summary

Debugging Missing Metadata

Next Steps