oapi-codegen icon indicating copy to clipboard operation
oapi-codegen copied to clipboard

`allOf` schema description in YAML file is not used as comment for the struct in generated code

Open Shakhrik opened this issue 10 months ago • 0 comments

When using allOf to embed other schemas, the description field of parent schema in the yaml file is not used as a comment for the generated struct. For example, given the following OpenAPI schema:

Person:
  type: object
  description: |
    This is a person, with mandatory first and last name, but optional ID
    number. This would be returned by a `Get` style API. We merge the person
    properties with another schema which only provides required fields.
  allOf:
    - $ref: "#/components/schemas/PersonProperties"
    - required: [ FirstName, LastName ]

PersonWithID:
  type: object
  description: |
    This is a person record as returned from a Create endpoint. It contains
    all the fields of a Person, with an additional resource UUID.
  allOf:
    - $ref: "#/components/schemas/Person"
    - properties:
        ID:
          type: integer
          format: int64
      required: [ ID ]

The generated Go code looks like this:

// PersonWithID defines model for PersonWithID.
type PersonWithID struct {
	FirstName          string `json:"FirstName"`
	GovernmentIDNumber *int64 `json:"GovernmentIDNumber,omitempty"`
	ID                 int64  `json:"ID"`
	LastName           string `json:"LastName"`
}

In this case, the PersonWithID schema has its own description, but it is not reflected as a comment above the generated struct. Instead, a generic comment (defines model for PersonWithID) is used.

Expected behavior: The struct comment should ideally include or reflect the description field from the yaml file when available, even when the schema is composed using allOf. So the comment for PersonWithID in the generated code should look like this:

// PersonWithID This is a person record as returned from a Create endpoint. It contains
//  all the fields of a Person, with an additional resource UUID.
type PersonWithID struct {
	FirstName          string `json:"FirstName"`
	GovernmentIDNumber *int64 `json:"GovernmentIDNumber,omitempty"`
	ID                 int64  `json:"ID"`
	LastName           string `json:"LastName"`
}

Shakhrik avatar Apr 28 '25 06:04 Shakhrik