Examples
TypeSpec provide 2 decorators @example
and @opExample
to provide some examples for the types and operations.
With those decorators the examples must be provided as TypeSpec values that should be assignable to the type or operation parameter/return types.
Type Examples
Section titled “Type Examples”To give an example for a type you can use the @example
decorator. The decorator first argument is the example value it MUST be assignable to the type it is targetting.
Additionally a title and/or description can be provided in the options.
Simple primitive types
Section titled “Simple primitive types”@example(#{ name: "Max", age: 3 })model Pet { name: string; age: int32;}
Scalar types
Section titled “Scalar types”For scalar types the value must be defined with the scalar constructor.
This allows emitters to render the example in the correct protocol following the encoding of those scalar and the values set by @encode
.
@example(#{ id: "item-1", createdAt: plainDate.fromISO("2020-01-01T00:00:00Z"), timeout: duration.fromISO("PT1M"),})model Item { id: string; createdAt: utcDateTime; @encode("seconds", int32) timeout: duration;}
Provide title or description
Section titled “Provide title or description”@example(#{ name: "Max", age: 3 }, #{ title: "Pet example", description: "Simple pet example" })model Pet { name: string; age: int32;}
Multiple examples
Section titled “Multiple examples”@example(#{ name: "Max", age: 3 }, #{ title: "Minimal examples", description: "Minimal examples" })@example( #{ name: "Rex", age: 8, bark: true }, #{ title: "With optional properties", description: "Example where the pet barks" })model Pet { name: string; age: int32; bark?: boolean;}
Define typed examples using const
Section titled “Define typed examples using const”const petExample: Pet = #{ name: "Max", age: 3 };
@example(petExample)model Pet { name: string; age: int32;}
Operation examples
Section titled “Operation examples”Operation example are provided with the @opExample
decorator. Similar to the @example
decorator the first argument is the example value however it takes both the parameters
and returnType
example.
The values passed to parameters
MUST be assignable to the operation parameters and the value passed to returnType
MUST be assignable to the operation return type.
Additionally a title and/or description can be provided in the options.
Simple operation parameters
Section titled “Simple operation parameters”@opExample(#{ parameters: #{ name: "Max", age: 3 } })op write(name: string, age: int32): void;
Simple operation return types
Section titled “Simple operation return types”@opExample(#{ returnType: #{ name: "Max", age: 3 } })op read(): { name: string; age: int32;};
Specify title and/or description
Section titled “Specify title and/or description”@opExample( #{ parameters: #{ name: "Max", age: 3 } }, #{ title: "Simple write example", description: "Write a pet" })op write(name: string, age: int32): void;