Examples

[markcowl]

Implementation issue for: https://github.com/Azure/typespec-azure/issues/3540, #514. Design details are here

• Update versioning decorators to accommodate 'never' for the version argument (meaning do not execute the decorator)

• Add templates and decorators to OpenAPI library

  • Add JsonExample templates, and, in private namespace, @jsonExampleName, @jsonExampleLiteral , @jsonExampleParameters, @jsonExampleReturnValue decorators and associated accessors:

    @jsonExampleName(TName)
    @added(TVersionAdded)
    @removed(TVersionRemoved)
    model JsonExampleOptions<
      TName extends string = null,
      TVersionAdded extends EnumMember = never,
      TVersionRemoved extends EnumMember = never> {}
  
    @jsonExampleLiteral(TExample)
    model JsonExample<
      TExample extends unknown,
      TName extends string = null,
      TSummary extends string = null,
      TVersionAdded extends EnumMember = never,
      TVersionRemoved extends EnumMember = never
    > is ExampleOptions<TName, TVersionAdded, TVersionRemoved> {}
  
    // This is specifically for matching return values in OpenAPI, with a
    // model keyed by status code
    @jsonExampleParameters(TParams)
    @jsonExampleReturnValue(TReturnValue)
    model JsonOperationExample<
      TParams extends {},
      TReturnValue extends Model | Model[],
      TName extends string = null,
      TSummary extends string = null,
      TVersionAdded extends EnumMember = never,
      TVersionRemoved extends EnumMember = never
    > is ExampleOptions<TName, TVersionAdded, TVersionRemoved> {}

  • Add @jsonExample decorator and associated accessors

  extern dec jsonExample(target: Model | ModelProperty , example: unknown)
  extern dec jsonOperationExample(target: Operation , example: unknown)

  • Add JsonExternalExample templates and associated decorator (@jsonExamplePath and accessor in private namespace)

  @jsonExamplePath(TExternalValue)
  model JsonExternalExample<
    TExternalValue extends string,
    TName extends string,
    TSummary extends string = null,
    TVersionAdded extends EnumMember = never,
    TVersionRemoved extends EnumMember = never
  > is ExampleOptions<TName, TVersionAdded, TVersionRemoved> {}

  • Add @jsonExternalExample decorator and associated accessors

  extern dec jsonExternalExample(target: Model | ModelProperty | Operation, externalExample: unknown)

• Implement OpenAPI3 example support based on decorators

  • Model and ModelProperty examples: support inlined value examples and named examples:

  TypeSpec

  @jsonExample(
    JsonExample<
      {type: "bar", createdAt: "2023-03-01T19:00:00Z"}, 
      TName = "bar-example", 
      TSummary ="An example of a bar type foo">)
  model Foo {
    type: "bar" | "baz"
    @jsonExample("2023-03-01T19:00:00Z")
    createdAt: utcDateTime;
  }

  Corresponding OpenAPI3

    Foo:
     type: object
     examples:
       bar-example:
         summary: "An example of a bar type foo"
         value:
           type: "bar"
           createdAt: "2023-03-01T19:00:00Z"
     properties:
       createdAt: 
         type: string
         format: date-time
         examples:
           - "2023-03-01T19:00:00Z"

  • Example file support in OpenAPI3

  TypeSpec

  @jsonExternalExample(
    JsonExternalExample<
      "examples/simple-foo-example.json", 
      TName = "simple-foo-example", 
      TSummary ="A simple example of type foo">)
  model Foo {
    type: "bar" | "baz"
    createdAt: utcDateTime;
  }

  Corresponding OpenAPI:

    Foo:
       type: object
       examples:
         simple-foo-example:
           summary: A simple example of type foo
           externalValue: 'examples/simple-foo-example.json'
       properties:
         createdAt: 
           type: string
           format: date-time

[markcowl]

est: 13