Question: how to support multiple content-types for the same response?

[lah-wag]

Hey,

Is it possible to describe a response with multiple content-types using tspec?
Example from: https://swagger.io/docs/specification/describing-responses/

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
            application/xml:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
            text/plain:
              schema:
                type: string

It seems that I would add the mediatype as js-doc to the reponse like in this example: https://ts-spec.github.io/tspec/guide/file-upload-download#file-download

export type UserApiSpec = Tspec.DefineApiSpec<{
  tags: ["Users"];
  paths: {
    "/api/users": {
      get: {
        summary: "Get all users";
        responses: {
          /** @mediaType application/json */
          /** @mediaType text/xml */
          200: Users[];
        };
      };
    };
  };
}>;

But that just takes the last value:

  "/api/users": {
      "get": {
        "operationId": "UserApiSpec_get_/api/users",
        "tags": [
          "Users"
        ],
        "summary": "Get all users",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "text/xml": {
                "schema": {
                  "mediaType": "text/xml",
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Users"
                  }
                }
              }
            }
          }
        }
      }
    }

[hyeonss0417]

We don't support multiple content-types yet, but we'll work on it in the near future.

I'm thinking of working with the following format, what do you think?

export type UserApiSpec = Tspec.DefineApiSpec<{
  tags: ["Users"];
  paths: {
    "/api/users": {
      get: {
        summary: "Get all users";
        responses: {
          /** @mediaType ["application/json", "text/xml"] */
          200: Users[];
        };
      };
    };
  };
}>;

[lah-wag]

We don't support multiple content-types yet, but we'll work on it in the near future.

I'm thinking of working with the following format, what do you think?

export type UserApiSpec = Tspec.DefineApiSpec<{
  tags: ["Users"];
  paths: {
    "/api/users": {
      get: {
        summary: "Get all users";
        responses: {
          /** @mediaType ["application/json", "text/xml"] */
          200: Users[];
        };
      };
    };
  };
}>;

Glad that you find it useful and will consider adding the feature.
To align with OpenAPI I think that individual mediatypes should have their own response object. Something like this:

export type UserApiSpec = Tspec.DefineApiSpec<{
  tags: ["Users"];
  paths: {
    "/api/users": {
      get: {
        summary: "Get all users";
        responses: {
             200: {
               "application/json": Users[],
               "application/xml": UsersXML[],
               "text/plain": string,
             }
        };
      };
    };
  };
}>;

Obviously this example should be reworked to use annotations instead.

[yeonjoon-ridi]

any updates on this? @hyeonss0417 we'd appreciate update on multipart/form-data

[hyeonss0417]

@yeonjoon-ridi
If you only want to use multipart/form-data, you can follow the instructions below, as described in the Tspec official documentation.

export type FileApiSpec = Tspec.DefineApiSpec<{
  paths: {
    '/files/upload': {
      post: {
        summary: 'Upload File',
        /** @mediaType multipart/form-data */
        body: {
          file: Tspec.BinaryString;
        },
        responses: { 200: { fileName: string } },
      },
    },
  },
}>;

https://ts-spec.github.io/tspec/guide/file-upload-download

Or do you want to create schemas with multiple response formats within the same status code, as discussed above?

[hyeonss0417]

Update: This feature is still on our roadmap.

Based on the discussion above, we're considering two approaches:

Option 1: Array syntax for same schema

responses: {
  /** @mediaType ["application/json", "text/xml"] */
  200: Users[];
}

Option 2: Object syntax for different schemas per content-type

responses: {
  200: {
    "application/json": Users[];
    "application/xml": UsersXML[];
    "text/plain": string;
  }
}

Option 2 aligns better with OpenAPI spec and provides more flexibility, but requires more significant changes to the type system.

We'll prioritize this feature in an upcoming release. In the meantime, if you need multiple content-types, you can:

1. Use the primary content-type with @mediaType
2. Post-process the generated spec to add additional content-types

Stay tuned for updates!