Repository navigation
Permit multiple externalDocs #1034
Description
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.
Activity
whitlockjc commentedon Apr 11, 2017
I could see this being useful.
darrelmiller commentedon Apr 13, 2017
I think I would be tempted to point to single HTML file that had links to other docs from there. I think if we start trying to describe different kinds of external docs in OpenAPI we are going to quickly run into a set of requirements for metadata about those docs.
webron commentedon Apr 19, 2017
Marked as post 3.0. We may or may not implement it, but 3.0 is feature complete and this request is not critical enough to break that.
micheldumontier commentedon Oct 26, 2017
Would very much like to be able to make a list. in the bioinformatics/life science community community, it's always nice to add links to published work about the API
rstavchansky commentedon Apr 30, 2018
I would use this suggested feature to point users to specific example workflows. We have more than one per endpoint.
fernando-ck commentedon Jul 29, 2019
I'd also like to have this feature implemented. Our documentation is based on multiple resources which would be useful if put on the same list.
nogates commentedon Jul 30, 2019
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 theexternalDocsmap objectkholmukhamedovme commentedon Dec 5, 2019
@webron any updates since 19 Apr 2017 when you marked this enhancement as post 3.0?
webron commentedon Dec 8, 2019
@kholmukhamedovme no additional work was done about this, likely as it did not attract a lot of attention compared to other issues. That said, anyone in the community can make a proposal to push this forward if they find it's important enough. More information can be found at https://github.com/OAI/OpenAPI-Specification/blob/master/DEVELOPMENT.md.
pjungermann commentedon Jan 28, 2020
another alternative: use Markdown to add links to the description field(s). It is probably not as elegant and not as machine readable as the suggested solution above, but you can still provide the information you want, organized as you want. Tooling might have different support for this, but as long as they support some Markdown, basic links should work.
Gypsying commentedon Nov 23, 2020
how is going now ?
1 remaining item
shaedrich commentedon Apr 6, 2022
Maybe, it would be helpful to add a
type(but that might(!) imply (but not necessarily require) metadata as @darrelmiller pointed out) property for the aforementioned factors alongside with a label@pjungermann There is another issue, pointing out using
$refproperty underdescription: #1402xaviqo commentedon Sep 29, 2022
Bumping this. I also think this would be useful.
y4my4my4m commentedon Feb 7, 2023
Bump, needed this feature today.
darrelmiller commentedon Feb 7, 2023
@y4my4my4m Would it be possible to provide examples of how this would have been useful for you? We should definitely revisit this issue in moonwalk.
y4my4my4m commentedon Feb 7, 2023
@darrelmiller
Some payload are used by both client and server and I'm trying to give reference to both.
In some cases I'm providing links to multiple examples as well (for different use cases).
suguiura-pp commentedon Nov 14, 2023
I think
externalDocsshould accept zero, one, or more external documents, since development teams might need to gather multiple business documents or even domains to consolidate an API.Is there any reason why this field accepts only zero or one "externalDoc" so far?
handrews commentedon Oct 14, 2026
@lornajane has a proposal for this in PR #5467.