microsoft / microsoft/kiota

[java] Unusable code emitted when a field is overwritten

Open
#2,304 13 comments 0 reactions 1 assignee View on GitHub

@andreaTP is already working on this.

Since Nov 23, 2023.

generator help wanted type:bug
Dominant language
C#
Stars
3.8k
Forks
333
Avg merge
16h 29m
Merged PRs (30d)
116

Description

This is clearly an edge case, but I would still like to report it to gather feedback.

I keep finding this pattern:

openapi: 3.0.3
info:
  title: Test API
  description: "A test API"
  version: 0.13.0-SNAPSHOT
paths:
  /api/v1/users:
    get:
      summary: Retrieves a list of users
      description: "Returns a list of all users"
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
components:
  schemas:
    List:
      required:
      - total
      - items
      type: object
      properties:
        kind:
          type: string
        items:
          type: array
          items:
            type: object
        total:
          format: int32
          description: Total number of entries in the full result set
          type: integer
          nullable: false
        size:
          format: int32
          description: Number of entries per page (returned for fetch requests)
          type: integer
        page:
          format: int32
          description: Current page number (returned for fetch requests)
          type: integer
    UserList:
      allOf:
      - $ref: '#/components/schemas/List'
      - description: List of users
        type: object
        properties:
          items:
            type: array
            items:
              type: string

The intention is clear, declare an abstract List and have concrete instances of it overwriting the items field.
It's pretty clearly not defined behavior, but I keep finding it in various places and it shows that, probably, OpenAPI tooling is handling this (most of those)cases according to the intention (as opposed to the spec).

Removing the items field from the "parent" produces the expected output.

Now, I'm not sure how to proceed here, should we fail instead of silently producing unusable code? Or should we handle this case(since is quite popular) with some kind of overwriting mechanism?

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.