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.

Inizia esaminando la definizione di externalDocs e i suoi utilizzi ai livelli di documento, tag, path e operation. Confronta le forme proposte di array e oggetto con chiavi, incluso l’esempio di $ref sotto paths, e determina la forma dello schema accettata e i requisiti di compatibilità prima di considerare conclusa la issue.