Examples

@tsed/schema

Usage

import { Examples } from "@tsed/schema";

See /packages/specs/schema/src/decorators/common/examples.ts.

Overview

function Examples(examples: OpenSpecHash<OS3Example | OpenSpecRef>): ParameterDecorator;

• examples (OpenSpecHash<OS3Example | OpenSpecRef>): - Object mapping names to example definitions

Description

Adds named examples for parameters in OpenAPI 3.0 format.

The @Examples() decorator provides named examples specifically for parameters, following the OpenAPI 3.0 specification format. Unlike @Example(), this accepts an object with named example entries, each with a value and optional description.

Basic Usage

@Controller("/users")
class UserController {
  @Get("/:id")
  async getUser(
    @Examples({
      admin: {
        value: "admin-123",
        summary: "Admin user ID"
      },
      regular: {
        value: "user-456",
        summary: "Regular user ID"
      }
    })
    @PathParams("id")
    id: string
  ) {}
}

Query Parameters

@Get("/search")
async search(
  @Examples({
    simple: {
      value: "typescript",
      summary: "Simple keyword search"
    },
    complex: {
      value: "typescript AND nodejs",
      summary: "Boolean search query"
    }
  })
  @QueryParams("q")
  query: string
) {}

With Descriptions

@Post("/filter")
async filter(
  @Examples({
    basic: {
      value: { status: "active" },
      summary: "Filter by status",
      description: "Returns only active records"
    },
    advanced: {
      value: { status: "active", role: "admin" },
      summary: "Complex filter",
      description: "Combines multiple filter criteria"
    }
  })
  @BodyParams()
  filters: object
) {}

Use Cases

• Interactive Docs: Provide multiple example scenarios in Swagger UI
• API Education: Show different use cases with descriptions
• Testing: Reference examples for integration tests
• Client Generation: Provide varied examples for SDK documentation

OpenAPI 3.0 Format

Generates:

{
  "examples": {
    "admin": {
      "value": "admin-123",
      "summary": "Admin user ID"
    }
  }
}

vs @Example

• @Examples(): Named examples with summaries/descriptions (OpenAPI 3.0)
• @Example(): Simple array of values