[BUG][typescript-angular] Tagged Unions Not Working As Expected

Mar 12, 2025 by ADMIN 64 views

**BUG in TypeScript-Angular: Tagged Unions Not Working as Expected**

Introduction

In this article, we will delve into a bug that has been reported in the OpenAPI Generator, specifically in the TypeScript-Angular client generation. The bug is related to tagged unions, which are a feature in OpenAPI that allows for the creation of complex data types. However, when generating a TypeScript-Angular client with tagged unions, an empty interface is generated instead of the expected union type.

Bug Report Checklist

Before we dive into the details of the bug, let's go through the bug report checklist to ensure that we have a clear understanding of the issue.

Have you provided a full/minimal spec to reproduce the issue? Yes, a minimal OpenAPI declaration file has been provided to reproduce the issue.
Have you validated the input using an OpenAPI validator? Yes, the OpenAPI declaration file has been validated using an OpenAPI validator.
Have you tested with the latest master to confirm the issue still exists? Yes, the issue has been confirmed to exist in the latest master version of OpenAPI Generator.
Have you searched for related issues/PRs? Yes, a search has been conducted to ensure that this issue is not a duplicate of any existing issues or PRs.
What's the actual output vs expected output? The actual output is an empty interface, while the expected output is a union type.

Description of the Bug

The bug is related to the generation of a TypeScript-Angular client with tagged unions. When the taggedUnions property is set to true in the generation options, an empty interface is generated instead of the expected union type.

OpenAPI Declaration File Content

The OpenAPI declaration file that reproduces the issue is as follows:

openapi: 3.0.0
info:
  title: OpenAPI definition
  version: v0
paths:
  /api/test/zoo:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zoo'
components:
  schemas:
    Animal:
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
      required:
        - type
    Cat:
      allOf:
        - $ref: '#/components/schemas/Animal'
        - type: object
          properties:
            purrFrequency:
              type: integer
              format: int32
    Dog:
      allOf:
        - $ref: '#/components/schemas/Animal'
        - type: object
          properties:
            barkVolume:
              type: integer
              format: int32
    Zoo:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/Cat'
          - $ref: '#/components/schemas/Dog'

Generation Details

The generation details are as follows:

openapi-generator-cli generate -i ./allOf_composition_discriminator_collection.yaml -g typescript-angular -o ./out --additional-properties=taggedUnion=true

Steps to Reproduce

A failing test has been created to reproduce the issue. The test can be found in the following link: https://github.com/mikaelkaron/openapi-generator/blob/mikaelkaron-allOf_composition_discriminator_collection/modules/openapi-generator/src/test/java/org/openapitools/codegen/typescript/typescriptangular/TypeScriptAngularClientCodegenTest.java#L320-L345.

Conclusion

In conclusion, the bug in the OpenAPI Generator related to tagged unions not working as expected is a significant issue that needs to be addressed. The bug is reproducible with a minimal OpenAPI declaration file and a failing test has been created to demonstrate the issue. We hope that this article has provided a clear understanding of the bug and its impact on the OpenAPI Generator.

Recommendations

Based on the analysis of the bug, the following recommendations are made:

Fix the bug: The bug needs to be fixed to ensure that tagged unions work as expected in the OpenAPI Generator.
Improve testing: The testing framework needs to be improved to ensure that the bug is caught early and that the fix is thoroughly tested.
Provide better documentation: The documentation needs to be improved to provide better guidance on how to use tagged unions in the OpenAPI Generator.

Future Work

In the future, we plan to:

Continuously test the fix: The fix will be continuously tested to ensure that it works as expected.
Improve the testing framework: The testing framework will be improved to ensure that the bug is caught early and that the fix is thoroughly tested.
Provide better documentation: The documentation will be improved to provide better guidance on how to use tagged unions in the OpenAPI Generator.

Acknowledgments

Q: What is the bug in the OpenAPI Generator related to tagged unions?

A: The bug is related to the generation of a TypeScript-Angular client with tagged unions. When the taggedUnions property is set to true in the generation options, an empty interface is generated instead of the expected union type.

Q: What is a tagged union in OpenAPI?

A: A tagged union in OpenAPI is a feature that allows for the creation of complex data types. It is a way to define a union of multiple types, where each type is identified by a discriminator property.

Q: What is the expected output when generating a TypeScript-Angular client with tagged unions?

A: The expected output is a union type, where each type in the union is represented as a separate property in the interface.

Q: What is the actual output when generating a TypeScript-Angular client with tagged unions?

A: The actual output is an empty interface, which is not the expected output.

Q: How can I reproduce the bug?

A: You can reproduce the bug by creating a minimal OpenAPI declaration file that includes a tagged union, and then generating a TypeScript-Angular client with the taggedUnions property set to true.

Q: What is the impact of this bug on the OpenAPI Generator?

A: The bug has a significant impact on the OpenAPI Generator, as it prevents users from generating TypeScript-Angular clients with tagged unions.

Q: How can I contribute to the fix of this bug?

A: You can contribute to the fix of this bug by providing feedback, testing the fix, and providing documentation on how to use tagged unions in the OpenAPI Generator.

Q: What is the current status of the fix for this bug?

A: The fix for this bug is currently in progress, and we are working to ensure that it is thoroughly tested and documented.

Q: When can I expect the fix for this bug to be released?

A: We are working to release the fix for this bug as soon as possible, and we will provide updates on the status of the fix.

Q: How can I stay up-to-date with the latest developments on this bug?

A: You can stay up-to-date with the latest developments on this bug by following the OpenAPI Generator community, and by checking the OpenAPI Generator repository for updates.

Q: What are the next steps for the OpenAPI Generator community?

A: The next steps for the OpenAPI Generator community are to continue testing the fix, to improve the testing framework, and to provide better documentation on how to use tagged unions in the OpenAPI Generator.

Q: How can I get involved in the OpenAPI Generator community?

A: You can get involved in the OpenAPI Generator community by contributing to the fix of this bug, by testing the fix, and by providing feedback on how to improve the OpenAPI Generator.

Q: What are the benefits of contributing to the OpenAPI Generator community?

A: The benefits of contributing to the OpenAPI Generator community include the opportunity to improve the OpenAPI Generator, to gain experience in open-source development, and to connect with other developers who are passionate about API design and development.

Q: How can I learn more about the OpenAPI Generator community?

A: You can learn more about the OpenAPI Generator community by visiting the OpenAPI Generator website, by following the OpenAPI Generator community on social media, and by joining the OpenAPI Generator community on GitHub.