Examples (#3572)

Fix #2700 Add support for `@example` and `@opExample`


[Playground
demo](https://cadlplayground.z22.web.core.windows.net/prs/3572/?c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7Cgp1c2luZyBIdHRwOwoKQGV4YW1wbGUoI3sKICBpZDogInNvbWUiLAogIGJhcjogInRoaW5nxRBkYXRlOiB1dGNEYXRlVGltZS5mcm9tSVNPKCIyMDIwLTAxLTAxVDAwOsUDWiIpxDV1bml4xDA6xQrENnN0YW1wMzLfPcU9ZW5jb2RlZEFzUmZjNzIzMd9%2B0kFkb2I6IHBsYWluxDbUMsYodGltZW91dDogZHVyYXRpb27KK1BUMU3NJUluU2Vjb25kc9guMS41U9YyRmxvYddlMMc1fSkKbW9kZWwgRm9vIOgBlHN0cmluZzvoAZTKD%2FEBk8QV%2BQFzOwoKICBA5gFVKMgyS25vd25FxBRpbmcucuYBaSn%2FAX1lxUvuAV7Ee%2FEBSM1zInPmAQciLCBpbnQzMsRm%2BgFV2Dtm5AFF1j3vAWA7Cn0K5wFOUGV08wFObmFtZcwQ8ADRfQoKQG9wRecDIwogIOUDJiAgcGFyYW1ldGVyczrIE%2FADPcUnZXTLINQi6ACDIkZsdWZmecsY%2FwK66QK6xAF9xgnHB3JldHVyblR5cGX9AJ3Wed93y3fFbsUFI3sgdGl0bMVOaXJzdCIsIGRlc2NyaXDkAYU6ICJTaG93IGNyZWF05AR6YeQBGCIgfQopCm9wxhdlUGV0KOoBmyzEIjrkAbQpxQY7Cg%3D%3D&e=%40typespec%2Fopenapi3&options=%7B%7D)

---------

Co-authored-by: Brian Terlson <brian.terlson@microsoft.com>

.chronus/changes/examples-2024-5-12-22-55-41.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add support for new `@example` and `@opExample` decorator

.chronus/changes/examples-2024-5-14-18-46-26.md

@@ -0,0 +1,43 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Add new `@example` and `@opExample` decorator to provide examples on types and operations.
+
+  ```tsp
+  @example(#{
+    id: "some",
+    date: utcDateTime.fromISO("2020-01-01T00:00:00Z"),
+    timeout: duration.fromISO("PT1M"),
+  })
+  model Foo {
+    id: string;
+    date: utcDateTime;
+  
+    @encode("seconds", int32) timeout: duration;
+  }
+  ```
+
+  ```tsp
+  @opExample(
+    #{
+      parameters: #{
+        pet: #{
+          id: "some",
+          name: "Fluffy",
+          dob: plainDate.fromISO("2020-01-01"),
+        },
+      },
+      returnType: #{
+        id: "some",
+        name: "Fluffy",
+        dob: plainDate.fromISO("2020-01-01"),
+      },
+    },
+    #{ title: "First", description: "Show creating a pet" }
+  )
+  op createPet(pet: Pet): Pet;
+  ```

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 data type.
+```typespec
+@example(example: valueof unknown, options?: valueof ExampleOptions)
+```
+
+#### Target
+
+`Model | Enum | Scalar | Union | ModelProperty | UnionVariant`
+
+#### 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 example values for an operation's parameters and corresponding return 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

@@ -10,6 +10,7 @@ import type {
   Scalar,
   Type,
   Union,
+  UnionVariant,
 } from "../src/index.js";
 
 /**
@@ -571,6 +572,45 @@ export type DiscriminatorDecorator = (
   propertyName: string
 ) => void;
 
+/**
+ * Provide an example value for a data 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;
+ * }
+ * ```
+ */
+export type ExampleDecorator = (
+  context: DecoratorContext,
+  target: Model | Enum | Scalar | Union | ModelProperty | UnionVariant,
+  example: unknown,
+  options?: unknown
+) => void;
+
+/**
+ * Provide example values for an operation's parameters and corresponding return 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;
+ * ```
+ */
+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 data 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 | UnionVariant,
+  example: valueof unknown,
+  options?: valueof ExampleOptions
+);
+
+/**
+ * Operation example configuration.
+ */
+model OperationExample {
+  /** Example request body. */
+  parameters?: unknown;
+
+  /** Example response body. */
+  returnType?: unknown;
+}
+
+/**
+ * Provide example values for an operation's parameters and corresponding return 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

packages/compiler/package.json

@@ -91,6 +91,7 @@
     "prettier": "~3.3.2",
     "prompts": "~2.4.2",
     "semver": "^7.6.2",
+    "temporal-polyfill": "^0.2.5",
     "vscode-languageserver": "~9.0.1",
     "vscode-languageserver-textdocument": "~1.0.11",
     "yaml": "~2.4.5",