Permit multiple externalDocs

Documenting APIs often depend on multiple external factors - functional and non-functional aspects, change notes, governance, strategy, many more - and a single externalDocs reference is often insufficient, especially in complex scenarios where multiple parties are responsible for design/deployment/delivery of these aspects (not everyone is DevOps)

Would we want to move the single object to an array/collection of objects:

externalDocs:
- description: link 1
  url: http://link/1
- description: link
  url: http://link/2

or

externalDocs:
  link1:
    description: link 1
    url: http://link/1
  link2
    description: link
    url: http://link/2

Gong further, form 2 may also benefit from becoming a reference:

externalDocs:
  link1:
    url: http://link/1

paths:
  /path1:
    get:
      externalDocs:
      - $ref: '#/externalDocs/link1'

While some of this may overlap with (the single) externalDocs avaulable in a tag, it is not entirely overlapping, and the link should ideally reside close to where it is needed instead of tracking it back through a tag that may not be immediately apparent will contain the required link.

[nogates]

FWIW, I always found strange that the key was actually named externalDocs (plural) but only one link was allowed… I think it would make sense to go with the externalDocs map object

[xaviqo]

Bumping this. I also think this would be useful.