Skip to content

Use of allOf to document a field makes the field disappearΒ #2884

@ivucica

Description

@ivucica

Cheers,

Let's assume existence of User definition, and Submission definition. The Submission definition can contain User fields author and submitter. I'd like to document author and submitter.

I've went to editor.swagger.io. Having taken the petstore_full.yaml example, I've tried to apply the suggestion from OAI/OpenAPI-Specification#556 (comment 192007034). Taking the Pet definition:

  Pet:
    type: object
    required:
      - name
      - photoUrls
    properties:
      id:
        type: integer
        format: int64
      category:
        $ref: "#/definitions/Category"
    # etc

I've made the following change to category property:

      category:
        description: This is pet's category.
        allOf:
        - $ref: "#/definitions/Category"

I've tried to generate the Go code for this, but (aside from editor itself showing 'undefined' at one point) the generator made that field disappear.

It would be nice if the field didn't disappear, and if the description was put in the leading comment of the Go struct field.

There is an even worse behavior if you try to do this to an operation's parameter:

paths:
  /pets:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: ""
      operationId: addPet
      consumes:
        - application/json
        - application/xml
      produces:
        - application/json
        - application/xml
      parameters:
        - in: body
          name: body
          description: Pet object that needs to be added to the store
          required: false
          schema:
            description: bleh
            allOf:
            - $ref: "#/definitions/Pet"

which causes this (newlines added for readability):

Unable to build target:
Could not process operation: 
Tag: pet
Operation: addPet
Resource: post /pets
Definitions: {User=io.swagger.models.ModelImpl@1e62688a, Category=io.swagger.models.ModelImpl@5e24b60b, Pet=io.swagger.models.ModelImpl@bfb7fbb1, Tag=io.swagger.models.ModelImpl@5e24b60b, Order=io.swagger.models.ModelImpl@b8396aae}
Exception: null

(Of course, this issue applies only if the cited comment isn't misleading -- that is, if the spec is actually supposed to support this way of documenting property usages. I believe it'd be a very useful behavior, but maybe it's really not supposed to be supported at the moment.)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions