-
Notifications
You must be signed in to change notification settings - Fork 6k
Description
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.)