microsoft/kiota

[java] Unusable code emitted when a field is overwritten

Open

#2,304 opened on Feb 14, 2023

 (13 comments) (0 reactions) (1 assignee)C# (326 forks)auto 404
generatorhelp wantedtype:bug

Repository metrics

Stars
 (3,783 stars)
PR merge metrics
 (PR metrics pending)

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