Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Bug]: @example s not generating correct open api doc #5598

Open
4 tasks done
sconnon-repay opened this issue Jan 14, 2025 · 0 comments
Open
4 tasks done

[Bug]: @example s not generating correct open api doc #5598

sconnon-repay opened this issue Jan 14, 2025 · 0 comments
Labels
bug Something isn't working needs-area

Comments

@sconnon-repay
Copy link

sconnon-repay commented Jan 14, 2025

Describe the bug

2 separate issues here. Full reproducible examples below

  1. When using multiple @example s on a single model, only the latest is appended to the output open API yaml
  2. When using @examples inside aliased types, no example is generated and there are no compiler errors (if this is invalid usage)

Apologies if this is a duplicate, github search for "@example" gives me 100s of unrelated issues

Reproduction

Issue 1

Input:

import "@typespec/http";
import "@typespec/openapi3";

using TypeSpec.Http;

@service({
  title: "Widget Service",
})

namespace X;

@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;
}

Output: NOTE that "Max" is gone

openapi: 3.0.0
info:
  title: Widget Service
  version: 0.0.0
tags: []
paths: {}
components:
  schemas:
    Pet:
      type: object
      required:
        - name
        - age
      properties:
        name:
          type: string
        age:
          type: integer
          format: int32
        bark:
          type: boolean
      example:
        name: Rex
        age: 8
        bark: true

Issue 2

import "@typespec/http";
import "@typespec/openapi3";

using TypeSpec.Http;

@service({
  title: "Widget Service",
})

namespace X;

model Pet {
  name: string;
  age: int32;
  bark?: boolean;
}

alias Pet200 = { 
  @statusCode statusCode: 200; 
  @example(#{ name: "Max", age: 3 }, #{ title: "Minimal examples", description: "Minimal examples" })
  @body body: Pet; 
};

alias Pet201 = { 
  @statusCode statusCode: 201;
  @example(
    #{ name: "Rex", age: 8, bark: true },
    #{ title: "With optional properties", description: "Example where the pet barks" }
  )
  @body body: Pet; 
};

@route("pet")
@post()
op post(): Pet200 | Pet201;

Output: NOTE no examples

openapi: 3.0.0
info:
  title: Widget Service
  version: 0.0.0
tags: []
paths:
  /pet:
    post:
      operationId: post
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - name
        - age
      properties:
        name:
          type: string
        age:
          type: integer
          format: int32
        bark:
          type: boolean

Checklist

@sconnon-repay sconnon-repay added the bug Something isn't working label Jan 14, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working needs-area
Projects
None yet
Development

No branches or pull requests

1 participant