scribe-openapi

name	scribe-openapi
description	Scribe OpenAPI generation patterns for the Laravel API. Use when adding or updating API documentation annotations, regenerating openapi.json, or configuring Scribe. Triggers on tasks involving @group, @bodyParam, @response, @authenticated, openapi.json updates, or the api-client drift gate.
frameworks	["laravel","scribe"]
languages	["php"]
category	api
updated	"2026-04-29T00:00:00.000Z"

Scribe OpenAPI Skill

Quick Reference

When to Use: Adding endpoint docs, regenerating openapi.json, or updating Scribe config

Output: apps/laravel/openapi.json — consumed by packages/api-client and the CI drift gate

Regenerate command: pnpm -F @repo/laravel openapi:generate

Annotation Reference

Controller-Level (@group)

/**
 * @group Todos
 *
 * Manage the authenticated user's todo list.
 */
class TodoController extends Controller

Endpoint Annotations

/**
 * List todos
 *
 * Returns all todos belonging to the authenticated user,
 * ordered newest first.
 *
 * @authenticated
 *
 * @response 200 [
 *   {"id":1,"title":"Buy milk","completed":false,"created_at":"2025-01-01T00:00:00.000000Z"},
 *   {"id":2,"title":"Call dentist","completed":true,"created_at":"2025-01-02T00:00:00.000000Z"}
 * ]
 * @response 401 scenario="Unauthenticated" {"message":"Unauthenticated."}
 */
public function index(Request $request): AnonymousResourceCollection

/**
 * Create todo
 *
 * @authenticated
 *
 * @bodyParam title string required The todo title. Example: Buy eggs
 * @bodyParam completed boolean Whether the todo is already complete. Example: false
 *
 * @response 201 {"id":3,"title":"Buy eggs","completed":false,"created_at":"2025-01-03T00:00:00.000000Z"}
 * @response 422 scenario="Validation error" {"message":"The title field is required.","errors":{"title":["The title field is required."]}}
 */
public function store(StoreTodoRequest $request): TodoResource

URL Parameters

/**
 * Get todo
 *
 * @authenticated
 *
 * @urlParam id integer required The todo ID. Example: 1
 *
 * @response 200 {"id":1,"title":"Buy milk","completed":false}
 * @response 404 {"message":"Not found"}
 */
public function show(int $id): TodoResource

Auth Groups

/**
 * @group Auth (web)
 *
 * Cookie-based session authentication for the SPA.
 */

/**
 * @group Auth (mobile)
 *
 * Personal Access Token authentication for the Flutter app.
 */

Full Endpoint Example

/**
 * @group Tickets
 */
class TicketController extends Controller
{
    /**
     * List tickets
     *
     * Returns all tickets. Visible to all authenticated users.
     *
     * @authenticated
     *
     * @response 200 [{"id":1,"subject":"Server down","status":"open","role":"admin","created_at":"2025-01-01T00:00:00.000000Z"}]
     */
    public function index(): AnonymousResourceCollection
    {
        return TicketResource::collection(Ticket::latest()->get());
    }

    /**
     * Create ticket
     *
     * Admin-only. Returns 403 for non-admin users.
     *
     * @authenticated
     *
     * @bodyParam subject string required Ticket subject. Example: Server down
     * @bodyParam status  string required open|closed. Example: open
     *
     * @response 201 {"id":2,"subject":"Server down","status":"open","role":"admin"}
     * @response 403 scenario="Not admin" {"message":"This action is unauthorized."}
     */
    public function store(StoreTicketRequest $request): TicketResource
    {
        $this->authorize('create', Ticket::class);
        return new TicketResource(Ticket::create($request->validated()));
    }
}

Regenerating openapi.json

# From monorepo root
pnpm -F @repo/laravel openapi:generate

# What it does under the hood:
# 1. php artisan scribe:generate  → public/docs/openapi.yaml
# 2. Convert YAML → JSON          → openapi.json (at apps/laravel/)

After regenerating, always commit openapi.json alongside the code change. The CI drift gate (packages/e2e-web or .github/workflows/ci.yml) will fail if openapi.json is stale.

Scribe Config (config/scribe.php)

Key settings:

return [
    'type'  => 'laravel',       // Route extraction strategy
    'auth'  => [
        'enabled'  => true,
        'in'       => 'bearer', // Adds Authorization header in docs
        'name'     => 'token',
    ],
    'routes' => [
        [
            'match' => [
                'prefixes' => ['api/*'],
                'domains'  => ['*'],
            ],
        ],
    ],
    'postman' => ['enabled' => false],
    'openapi' => ['enabled' => true],
    'output_path' => 'public/docs',
];

CI Drift Gate

The CI pipeline has a job that:

1. Calls pnpm -F @repo/laravel openapi:generate
2. Diffs the output against the committed openapi.json
3. Fails if there are any changes (schema drift)

This ensures openapi.json is always in sync with the running API.

Adding New Endpoint Checklist

1. Implement controller method with appropriate HTTP verb and route
2. Add Scribe annotations: @group, @bodyParam, @urlParam, @response (happy + error)
3. Add @authenticated if the route uses auth:sanctum
4. Run pnpm -F @repo/laravel openapi:generate
5. Commit the updated openapi.json
6. Run pnpm -F @repo/api-client generate to update TypeScript hooks