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.

Start by reviewing the externalDocs definition and its uses at the document, tag, path, and operation levels. Compare the proposed array and keyed-object forms, including the $ref example under paths, and determine the accepted schema shape and compatibility requirements before considering the issue done.