Aliases should be kept as open api schemas

[csaba-veezla]

Clear and concise description of the problem

I feel like, this is almost a bug and not a feature request.

For a tsp declaration like this

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

using TypeSpec.Http;
using TypeSpec.Rest;

@doc("Example API")
@service({
  title: "Example",
})
namespace Example;

interface Examples{
  @get
  get(id: string): Elapsed;
}

model Elapsed {
  amount: integer;
  dateUnit: DateUnit;
}

alias DateUnit = "hours" | "days" | "weeks" | "months" | "years";

we get this open API spec

openapi: 3.0.0
info:
  title: Example
  description: Example API
tags: []
paths:
  /:
    get:
      operationId: Examples_get
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Elapsed'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
              required:
                - id
components:
  schemas:
    Elapsed:
      type: object
      required:
        - amount
        - dateUnit
      properties:
        amount:
          type: integer
        dateUnit:
          type: string
          enum:
            - hours
            - days
            - weeks
            - months
            - years

As you can see we lost a piece of information about the alias.
This could have easily resulted in the following:

openapi: 3.0.0
info:
  title: Example
  description: Example API
tags: []
paths:
  /:
    get:
      operationId: Examples_get
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Elapsed'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
              required:
                - id
components:
  schemas:
    Elapsed:
      type: object
      required:
        - amount
        - dateUnit
      properties:
        amount:
          type: integer
        dateUnit:
          type: string
          enum:
            - ref: '#/components/schemas/DateUnit'
    DateUnit:
      type: string
      enum:
        - hours
        - days
        - weeks
        - months
        - years

If the alias were to reference to models it could result into something like this:

    FilterValue:
      anyOf:
        - $ref: '#/components/schemas/MultiSelectFilterValue'
        - $ref: '#/components/schemas/DateFilterValue'

(If an alias is not pure models or scalars we can unpack them just like now.)

And with a result like this, a client generator can easily create a type for it or even a validator.

Or am I missing something in the docs and there is an option/flag for this?

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[timotheeguerin]

Alias are by design in the TypeSpec type graph non existent so it is not possible to retrieve their name.

If you want to create a union declaration you can use the union keyword or an enum would work in your case too

union DateUnit {
  "hours",
  "days",
  "weeks",
  "months",
  "years",
}

enum DateUnitEnum {
  hours,
  days,
  weeks,
  months,
  years,
}

playground

[csaba-veezla]

This was an issue on my part..
I'm fairly new to tsp and tried to use alias as it were union.. thanks for clearing it up.

Also, I saw that the results of circular dependencies do not play nice with the API spec emitter.

model MeuItem {
  label: string;
  // additional item props
}

model MenuGroup {
  label: string;
  // additional group props
  children: MenuItem | MenuGroup;
}

Is this a bug or is there another way to handle these cases?
In the API spec this will result in something like this:

 components:
  schemas:
    MenuGroup:
      type: object
      required:
        - label
        - children
      properties:
        label:
          type: string
        children:
          anyOf:
            - $ref: '#/components/schemas/MenuItem'
            - {}
    MenuItem:
      type: object
      required:
        - label
      properties:
        label:
          type: string

Edit: sorry for the late response.

[timotheeguerin]

Sorry never got back to you, yeah this looks like a bug in openapi3 emitter, json schema one seems to handle that correctly

https://cadlplayground.z22.web.core.windows.net/?c=aW1wb3J0ICJAdHlwZXNwZWMvanNvbi1zY2hlbWEiOwoKdXNpbmcgVHlwZVNwZWMuSnNvblPFHTsKCm5hbWVzcGFjZSDGE3M7CgpAxEDGDwptb2RlbCBNZW51R3JvdXAgewogIGxhYmVsOiBzdHJpbmc7CgogIC8vIGFkZGl0aW9uYWwgZ8UqcHJvcHMKICBjaGlsZHJlbjrFRkl0ZW0gfMpROwp9CstlxR%2FTZNBjacQoxmJ9Cg%3D%3D&e=%40typespec%2Fjson-schema&options=%7B%7D

[timotheeguerin]

Created a new issue specially for that #3811