{"action":"created","issue":{"url":"https://api.github.com/repos/swagger-api/swagger-editor/issues/1184","repository_url":"https://api.github.com/repos/swagger-api/swagger-editor","labels_url":"https://api.github.com/repos/swagger-api/swagger-editor/issues/1184/labels{/name}","comments_url":"https://api.github.com/repos/swagger-api/swagger-editor/issues/1184/comments","events_url":"https://api.github.com/repos/swagger-api/swagger-editor/issues/1184/events","html_url":"https://github.com/swagger-api/swagger-editor/issues/1184","id":207598518,"number":1184,"title":"Properties with \"$ref\" and \"description\" cause warnings in editor","user":{"login":"hlubovac","id":3127736,"avatar_url":"https://avatars3.githubusercontent.com/u/3127736?v=4","gravatar_id":"","url":"https://api.github.com/users/hlubovac","html_url":"https://github.com/hlubovac","followers_url":"https://api.github.com/users/hlubovac/followers","following_url":"https://api.github.com/users/hlubovac/following{/other_user}","gists_url":"https://api.github.com/users/hlubovac/gists{/gist_id}","starred_url":"https://api.github.com/users/hlubovac/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hlubovac/subscriptions","organizations_url":"https://api.github.com/users/hlubovac/orgs","repos_url":"https://api.github.com/users/hlubovac/repos","events_url":"https://api.github.com/users/hlubovac/events{/privacy}","received_events_url":"https://api.github.com/users/hlubovac/received_events","type":"User","site_admin":false},"labels":[{"id":96783399,"url":"https://api.github.com/repos/swagger-api/swagger-editor/labels/type:%20question","name":"type: question","color":"f9d0c4","default":false}],"state":"closed","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":16,"created_at":"2017-02-14T18:32:49Z","updated_at":"2018-03-19T09:31:07Z","closed_at":"2017-03-25T03:33:51Z","author_association":"NONE","body":"I'm having a hard time finding information about this in specs, so I can't guess whether the problem that I'm about to describe is by design or a if it's a bug.\r\n\r\nWhen, within `definitions`, an entry exists with a property referencing another definition via `$ref` **and also** having a `description` value, then swagger-editor shows a warning.\r\n\r\nIf it's only one, it wouldn't bother me as much, but my swagger-json is large, and I have dozens (and growing) of these. I'm trying to stay adamant with keeping the `description` field where it is (as opposed to moving it to the actual referenced definition, which is what fixes the problem), because otherwise [swagger-ui](https://github.com/swagger-api/swagger-ui) doesn't display it at all.\r\n\r\nFor example, the editor does not like `description` values in this YAML `definition` snippet):\r\n```\r\n  'response:container:collection:agent':\r\n    type: object\r\n    properties:\r\n      jsonapi:\r\n        $ref: '#/definitions/response:container:jsonapi'\r\n        description: Service information\r\n      meta:\r\n        $ref: '#/definitions/response:container:meta'\r\n        description: Request processing information\r\n      links:\r\n        $ref: '#/definitions/response:container:links'\r\n        description: URLs related to the primary resource(s)\r\n      data:\r\n        type: array\r\n        items:\r\n          $ref: '#/definitions/response:data:agent'\r\n      included:\r\n        type: array\r\n        items:\r\n          $ref: '#/definitions/response:container:related'\r\n        description: 'Related resources of types: \"lab\"'\r\n    required:\r\n      - data\r\n      - jsonapi\r\n      - links\r\n      - meta\r\n```\r\n... while swagger-ui displays those `description` values regardless (which I like):\r\n![image](https://cloud.githubusercontent.com/assets/3127736/22942733/f149fa06-f2a7-11e6-8c40-97b941487dfa.png)\r\n\r\nWhen 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).\r\n\r\nI did find some traces showing that my `description` values are where they are supposed to be - see this:\r\n\r\n![image](https://cloud.githubusercontent.com/assets/3127736/22942406/ae248170-f2a6-11e6-8b20-6ba11b621439.png)\r\n![image](https://cloud.githubusercontent.com/assets/3127736/22942419/babee182-f2a6-11e6-8720-3ee2e2532ca8.png)\r\n\r\nSource: http://json-schema.org/example1.html\r\n\r\n\r\nIt 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. E.g. 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\". 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 guess, if `description` can't be in both places, then if the two projects are at least in agreement about where it goes, it would help.\r\n\r\nThanks."},"comment":{"url":"https://api.github.com/repos/swagger-api/swagger-editor/issues/comments/374150632","html_url":"https://github.com/swagger-api/swagger-editor/issues/1184#issuecomment-374150632","issue_url":"https://api.github.com/repos/swagger-api/swagger-editor/issues/1184","id":374150632,"user":{"login":"vincnetas","id":472357,"avatar_url":"https://avatars3.githubusercontent.com/u/472357?v=4","gravatar_id":"","url":"https://api.github.com/users/vincnetas","html_url":"https://github.com/vincnetas","followers_url":"https://api.github.com/users/vincnetas/followers","following_url":"https://api.github.com/users/vincnetas/following{/other_user}","gists_url":"https://api.github.com/users/vincnetas/gists{/gist_id}","starred_url":"https://api.github.com/users/vincnetas/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vincnetas/subscriptions","organizations_url":"https://api.github.com/users/vincnetas/orgs","repos_url":"https://api.github.com/users/vincnetas/repos","events_url":"https://api.github.com/users/vincnetas/events{/privacy}","received_events_url":"https://api.github.com/users/vincnetas/received_events","type":"User","site_admin":false},"created_at":"2018-03-19T09:31:07Z","updated_at":"2018-03-19T09:31:07Z","author_association":"NONE","body":"Issue in OpenAPI spec repo https://github.com/OAI/OpenAPI-Specification/issues/1514"}}
{"actor":{"display_login":"vincnetas"}}