Use of allOf to document a field makes the field disappear

[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.)

[wing328]

@ivucica thanks for reporting the issue. Here are 2 suggestions:

1. use the latest master to generate the Go API client, which has 35 PRs (enhancement, bug fix) since the last stable release v2.1.6. (editor.swagger.io is using the latest stable version v2.1.6)

2. Go does not have any support of inheritance/model composition at the moment so I would suggest you to avoid using allOf to define your model for the time being. We plan to provide better support of inheritance/model composition to API clients in coming July

[ivucica]

Thanks for the response!

1. Sure. I'm doing this already when building locally, I just didn't verify with the local build.
2. The only reason for me to use allOf (or be aware of it!) is the above use case in Extra JSON Reference properties ignored - reduces reusability of references OAI/OpenAPI-Specification#556 comment 192007034 -- i.e. documenting how a field referencing a definition is to be used. I'm not really interested, at the moment, in any other use of allOf aside from attaching a piece of documentation to a field. :-)