Examples

docs/standard-library/built-in-data-types.md

@@ -39,6 +39,20 @@ model DefaultKeyVisibility<Source, Visibility>
 #### Properties
 None
 
+### `ExampleOptions` {#ExampleOptions}
+
+Options for example decorators
+```typespec
+model ExampleOptions
+```
+
+
+#### Properties
+| Name | Type | Description |
+|------|------|-------------|
+| title? | [`string`](#string) | The title of the example |
+| description? | [`string`](#string) | Description of the example |
+
 ### `object` {#object}
 
 Represent a model
@@ -83,6 +97,20 @@ model OmitProperties<Source, Keys>
 #### Properties
 None
 
+### `OperationExample` {#OperationExample}
+
+Operation example configuration.
+```typespec
+model OperationExample
+```
+
+
+#### Properties
+| Name | Type | Description |
+|------|------|-------------|
+| parameters? | `unknown` | Example request body. |
+| returnType? | `unknown` | Example response body. |
+
 ### `OptionalProperties` {#OptionalProperties}
 
 Represents a collection of optional properties.

docs/standard-library/built-in-decorators.md

@@ -214,6 +214,34 @@ op get(): Pet | NotFound;
 ```
 
 
+### `@example` {#@example}
+
+Provide an example value for a type.
+```typespec
+@example(example: valueof unknown, options?: valueof ExampleOptions)
+```
+
+#### Target
+
+`Model | Enum | Scalar | Union | ModelProperty`
+
+#### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| example | `valueof unknown` | Example value. |
+| options | [valueof `ExampleOptions`](./built-in-data-types.md#ExampleOptions) | Optional metadata for the example. |
+
+#### Examples
+
+```tsp
+@example(#{name: "Fluffy", age: 2})
+model Pet {
+ name: string;
+ age: int32;
+}
+```
+
+
 ### `@format` {#@format}
 
 Specify a known data format hint for this string type. For example `uuid`, `uri`, etc.
@@ -570,6 +598,31 @@ scalar distance is float64;
 ```
 
 
+### `@opExample` {#@opExample}
+
+Provide an example value for a type.
+```typespec
+@opExample(example: valueof OperationExample, options?: valueof ExampleOptions)
+```
+
+#### Target
+
+`Operation`
+
+#### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| example | [valueof `OperationExample`](./built-in-data-types.md#OperationExample) | Example value. |
+| options | [valueof `ExampleOptions`](./built-in-data-types.md#ExampleOptions) | Optional metadata for the example. |
+
+#### Examples
+
+```tsp
+@example(#{parameters: #{name: "Fluffy", age: 2}, returnType: #{name: "Fluffy", age: 2, id: "abc"})
+op createPet(pet: Pet): Pet;
+```
+
+
 ### `@overload` {#@overload}
 
 Specify this operation is an overload of the given operation.

packages/compiler/generated-defs/TypeSpec.ts

@@ -571,6 +571,20 @@ export type DiscriminatorDecorator = (
   propertyName: string
 ) => void;
 
+export type ExampleDecorator = (
+  context: DecoratorContext,
+  target: Model | Enum | Scalar | Union,
+  example: unknown,
+  options?: unknown
+) => void;
+
+export type OpExampleDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  example: unknown,
+  options?: unknown
+) => void;
+
 /**
  * Indicates that a property is only considered to be present or applicable ("visible") with
  * the in the given named contexts ("visibilities"). When a property has no visibilities applied

packages/compiler/generated-defs/TypeSpec.ts-test.ts

@@ -7,6 +7,7 @@ import {
   $encodedName,
   $error,
   $errorsDoc,
+  $example,
   $format,
   $friendlyName,
   $inspectType,
@@ -22,6 +23,7 @@ import {
   $minLength,
   $minValue,
   $minValueExclusive,
+  $opExample,
   $overload,
   $parameterVisibility,
   $pattern,
@@ -49,6 +51,7 @@ import type {
   EncodedNameDecorator,
   ErrorDecorator,
   ErrorsDocDecorator,
+  ExampleDecorator,
   FormatDecorator,
   FriendlyNameDecorator,
   InspectTypeDecorator,
@@ -64,6 +67,7 @@ import type {
   MinLengthDecorator,
   MinValueDecorator,
   MinValueExclusiveDecorator,
+  OpExampleDecorator,
   OverloadDecorator,
   ParameterVisibilityDecorator,
   PatternDecorator,
@@ -119,6 +123,8 @@ type Decorators = {
   $projectedName: ProjectedNameDecorator;
   $encodedName: EncodedNameDecorator;
   $discriminator: DiscriminatorDecorator;
+  $example: ExampleDecorator;
+  $opExample: OpExampleDecorator;
   $visibility: VisibilityDecorator;
   $withVisibility: WithVisibilityDecorator;
   $inspectType: InspectTypeDecorator;
@@ -163,6 +169,8 @@ const _: Decorators = {
   $projectedName,
   $encodedName,
   $discriminator,
+  $example,
+  $opExample,
   $visibility,
   $withVisibility,
   $inspectType,

packages/compiler/lib/std/decorators.tsp

@@ -500,6 +500,66 @@ extern dec encode(
   encodedAs?: Scalar
 );
 
+/** Options for example decorators */
+model ExampleOptions {
+  /** The title of the example */
+  title?: string;
+
+  /** Description of the example */
+  description?: string;
+}
+
+/**
+ * Provide an example value for a type.
+ *
+ * @param example Example value.
+ * @param options Optional metadata for the example.
+ *
+ * @example
+ *
+ * ```tsp
+ * @example(#{name: "Fluffy", age: 2})
+ * model Pet {
+ *  name: string;
+ *  age: int32;
+ * }
+ * ```
+ */
+extern dec example(
+  target: Model | Enum | Scalar | Union | ModelProperty,
+  example: valueof unknown,
+  options?: valueof ExampleOptions
+);
+
+/**
+ * Operation example configuration.
+ */
+model OperationExample {
+  /** Example request body. */
+  parameters?: unknown;
+
+  /** Example response body. */
+  returnType?: unknown;
+}
+
+/**
+ * Provide an example value for a type.
+ *
+ * @param example Example value.
+ * @param options Optional metadata for the example.
+ *
+ * @example
+ *
+ * ```tsp
+ * @example(#{parameters: #{name: "Fluffy", age: 2}, returnType: #{name: "Fluffy", age: 2, id: "abc"})
+ * op createPet(pet: Pet): Pet;
+ * ```
+ */
+extern dec opExample(
+  target: Operation,
+  example: valueof OperationExample,
+  options?: valueof ExampleOptions
+);
 /**
  * Indicates that a property is only considered to be present or applicable ("visible") with
  * the in the given named contexts ("visibilities"). When a property has no visibilities applied