OpenAPITools / OpenAPITools/openapi-generator

[REQ] Unifying Various different generator behaviour around AllOf/Inheritance

Open
#12,872 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Is your feature request related to a problem? Please describe.

When working with OpenAPI file and generator we often use single target language from single OpenAPI file.
In this scenario developers can tweak openapi file in case of some issues in generated SDKs (which is often neeed)

However there are number of usages where developers will be generating multiple libraries/SDKS from single OpenAPI file
In that scenario we often see many issues with handling of allOf and oneOf statement.
There is no one unified standard across different generators for inheritance and merges of the fields.

Desired outcomes in one generator = compilation issue on others

Imagine following object:

 Error:
      type: object
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      properties:
        id:
          type: string

This object represents json schema example for inheritance, generates desired state for model in most of the Java generators.
However It does break TypeScript and Golang Generators

Case 2:

 Error:
      type: object
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      -  properties:
          id:
            type: string

This use case does generate functional results in most of the generators, but..
in almost all examples does it by creating strangely named ErrorAllOf objects instead of adding fields to Error object.

Case 3:

 Error:
      type: object
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      - title: AnotherObject 
         properties:
          id:
            type: string

This case completely breaks everything on multiple generators like typescript - properties in AnotherObject aren't visbile anymore for users of Error

Describe the solution you'd like

I would like to help with documenting desired inheritance format for OpenAPI generator that users should put into their OpenAPI.
Both JSON schema and OpenAPI as standard really lacking an unified way to express inheritance models across the languages.
Each language would have different semantics and feature but at minimum there should be a way we can express simplied way to merge all properties that works for each language itself.

Then we can check for possible bugs and contribute changes to all generators.
I have been generating various different SDKs for the last 2 years using openapi generator and allOf support is the most common problem we deal with.

Describe alternatives you've considered

Have different openapi file per language

Additional context

Once can take look on differences in RHOAS SDKs repositories.
https://github.com/topics/rhoas-sdk

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the three allOf examples in the issue with the linked RHOAS SDK repositories and the behavior of the affected generators. Done means documenting a recommended inheritance format for OpenAPI inputs, along with the generator-specific limitations or inconsistencies that remain.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.