OpenAPI Spec incorrectly generated when creating API ME

[rabwill]

Describe the bug
When using reusable components as part of schema definition in the OpenAPI spec, the scaffolded yaml file is incorrectly generated

To Reproduce
Steps to reproduce the behavior:
Refer to below OpenAPI spec

openapi: 3.0.0
info:
  title: Alpha Vantage Stock Quote API
  version: 1.0.0
  description: API to fetch the latest stock quote from Alpha Vantage.
servers:
  - url: https://www.alphavantage.co
paths:
  /query:
    get:
      summary: Get the latest global stock quote
      description: Returns the latest trading information for the specified stock symbol using the Alpha Vantage Global Quote function.
      tags: [Global Quote]
      parameters:
        - in: query
          name: function
          schema:
            type: string
            default: GLOBAL_QUOTE
          required: true
          description: The API function to execute.
        - in: query
          name: symbol
          schema:
            type: string
          required: true
          description: The stock symbol for which to retrieve the quote.
        - in: query
          name: outputsize
          schema:
            type: string
            default: full
          required: false
          description: The output size of the stock data. Can be `compact` or `full`.
      responses:
        '200':
          description: A stock quote object containing the latest trading information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockQuoteResponse'
        '400':
          description: Bad Request - Invalid or missing query parameters.
        '404':
          description: Not Found - The requested symbol does not exist.
        '500':
          description: Internal Server Error - Error fetching stock quote from Alpha Vantage.
components:
  schemas:
    StockQuoteResponse:
      type: object
      properties:
        '01. symbol':
          type: string
          description: The stock symbol for the equity.
        '02. open':
          type: string
          description: The opening price for the stock on the latest trading day.
        '03. high':
          type: string
          description: The highest price at which the stock traded during the latest trading day.
        '04. low':
          type: string
          description: The lowest price at which the stock traded during the latest trading day.
        '05. price':
          type: string
          description: The closing price of the stock for the latest trading day.
        '06. volume':
          type: string
          description: The volume of shares traded on the latest trading day.
        '07. latest trading day':
          type: string
          description: The date of the latest trading day in YYYY-MM-DD format.
        '08. previous close':
          type: string
          description: The closing price of the stock for the previous trading day.
        '09. change':
          type: string
          description: The monetary change in the closing price from the previous trading day to the latest trading day.
        '10. change percent':
          type: string
          description: The percentage change in the closing price from the previous trading day to the latest trading day.

• Create an API based ME using the above spec.
• Open the project that is scaffolded by TTK
• Inspect the openapi.yaml file.

Expected behavior
A valid OpenAPI spec document similar to the one referenced

Screenshots

VS Code Extension Information (please complete the following information):

• OS: macOS Sonoma 14.3.1
• Version: 1.87.0 (Universal)

[microsoft-github-policy-service]

Thank you for contacting us! Any issue or feedback from you is quite important to us. We will do our best to fully respond to your issue as soon as possible. Sometimes additional investigations may be needed, we will usually get back to you within 2 days by adding comments to this issue. Please stay tuned.

[SLdragon]

Hi, @rabwill ,

The behavior observed in the generated YAML file is as expected. We utilize the "@apidevtools/swagger-parser" and "js-yaml" libraries to serialize the OpenAPI spec file in the Teams Toolkit.

The ">-" symbol in the YAML file eliminates trailing blank lines, enabling you to write lengthy descriptions without line length concerns.

The "*ref_0" notation signifies a reference to a reusable component. You can locate the component's position in the generated YAML file, marked as "&ref_0". This is because when parse OpenAPI spec file, component part is dropped, so it will use *ref_x and &ref_x for reuse component.

[rabwill]

Thanks for letting me know it is expected but this is the yaml file generated. Here the response has the schema it is as object, not as reusable component.

openapi: 3.0.0
info:
  title: Alpha Vantage Stock Quote API
  version: 1.0.0
  description: API to fetch the latest stock quote from Alpha Vantage.
servers:
  - url: https://www.alphavantage.co
paths:
  /query:
    get:
      summary: Get the latest global stock quote
      description:
        Returns the latest trading information for the specified stock symbol
        using the Alpha Vantage Global Quote function.
      tags:
        - Global Quote
      parameters:
        - in: query
          name: function
          schema:
            type: string
            default: GLOBAL_QUOTE
          required: true
          description: The API function to execute.
        - in: query
          name: symbol
          schema:
            type: string
            default: MSFT
          required: true
          description: The stock symbol for which to retrieve the quote.
        - in: query
          name: outputsize
          schema:
            type: string
            default: full
          required: false
          description: The output size of the stock data. Can be `compact` or `full`.
      responses:
        '200':
          description: A stock quote object containing the latest trading information.
          content:
            application/json:
              schema: &ref_0
                type: object
                properties:
                  01. symbol:
                    type: string
                    description: The stock symbol for the equity.
                  02. open:
                    type: string
                    description: The opening price for the stock on the latest trading day.
                  03. high:
                    type: string
                    description: >-
                      The highest price at which the stock traded during the
                      latest trading day.
                  04. low:
                    type: string
                    description: >-
                      The lowest price at which the stock traded during the
                      latest trading day.
                  05. price:
                    type: string
                    description: The closing price of the stock for the latest trading day.
                  06. volume:
                    type: string
                    description: The volume of shares traded on the latest trading day.
                  07. latest trading day:
                    type: string
                    description: The date of the latest trading day in YYYY-MM-DD format.
                  08. previous close:
                    type: string
                    description: >-
                      The closing price of the stock for the previous trading
                      day.
                  09. change:
                    type: string
                    description: >-
                      The monetary change in the closing price from the previous
                      trading day to the latest trading day.
                  10. change percent:
                    type: string
                    description: >-
                      The percentage change in the closing price from the
                      previous trading day to the latest trading day.
        '400':
          description: Bad Request - Invalid or missing query parameters.
        '404':
          description: Not Found - The requested symbol does not exist.
        '500':
          description: >-
            Internal Server Error - Error fetching stock quote from Alpha
            Vantage.
      operationId: getQuery
components:
  schemas:
    StockQuoteResponse: *ref_0

Is this also expected behaviour? How would it look if I have another operation that will also give me StockQuoteResponse?

[SLdragon]

you can search &ref_0 to find the real definition location for StockQuoteResponse, from your above schema, and in the 200 response you can find it:

So the StockQuoteResponse definition is as below:

type: object
properties:
  01. symbol:
    type: string
    description: The stock symbol for the equity.
  02. open:
    type: string
    description: The opening price for the stock on the latest trading day.
  03. high:
    type: string
    description: >-
      The highest price at which the stock traded during the
      latest trading day.
  04. low:
    type: string
    description: >-
      The lowest price at which the stock traded during the
      latest trading day.
  05. price:
    type: string
    description: The closing price of the stock for the latest trading day.
  06. volume:
    type: string
    description: The volume of shares traded on the latest trading day.
  07. latest trading day:
    type: string
    description: The date of the latest trading day in YYYY-MM-DD format.
  08. previous close:
    type: string
    description: >-
      The closing price of the stock for the previous trading
      day.
  09. change:
    type: string
    description: >-
      The monetary change in the closing price from the previous
      trading day to the latest trading day.
  10. change percent:
    type: string
    description: >-
      The percentage change in the closing price from the
      previous trading day to the latest trading day.