In other words, I think that both editor and swagger-ui should add the missing functionality in their code base, cause there's an obvious mismatch. I could say that my $ref "agent" is "a record that represents an employee", while my data property can be described as "collection of agents". It seems logical to me that both locations should allow description field: it may be desired that the definition ( $ref) is described in some generic way, while its usage ( properties) is described in addition to that. I did find some traces showing that my description values are where they are supposed to be - see this: When I move those description fields to definition of objects that $ref values point to, then swagger-editor shows the content as valid (so, no warning), but swagger-ui does not display those description values at all (not at the property level, not at the type level). while swagger-ui displays those description values regardless (which I like): $ref: '#/definitions/response:container:related'ĭescription: 'Related resources of types: "lab"' $ref: '#/definitions/response:data:agent' ![]() ![]() $ref: '#/definitions/response:container:links'ĭescription: URLs related to the primary resource(s) $ref: '#/definitions/response:container:meta'ĭescription: Request processing information $ref: '#/definitions/response:container:jsonapi'
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |