oapi-codegen
oapi-codegen copied to clipboard
`allOf` schema description in YAML file is not used as comment for the struct in generated code
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"`
}