OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
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.
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.
From my perspective, a spec file is the single source for particular APIs, and should have the multiple links per topic. Turning the API spec into the single source for multiple links in-place (as opposed to a link to somewhere to find a bunch of links) is useful, especially as I mentioned they should ideally be close to the place where you need them - not in some other file. The current approach only provides a limited enhancement to the spec file's utility and my proposal removes some of the burden from the designer: If that "single HTML file" doesn't yet exist, the designer is forced to create/find/host one, format it, etc. All of that is already handled in the API rendering or the raw spec file. I'm just proposing allowing multiple instances of the existing object class to expand its' utility. I don't think it's useful to enrich the links in the spec beyond the current description attribute, this isn't a CMS.
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.
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
I would use this suggested feature to point users to specific example workflows. We have more than one per endpoint.
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.
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
@webron any updates since 19 Apr 2017 when you marked this enhancement as post 3.0?
@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.
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.
Sorry for bumping this necropost. But personally i think this would be nice since it would also work as a "workaround", enabling links to specific project Slack channels for example.
multiple external factors - functional and non-functional aspects, change notes, governance, strategy, many more
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
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.
@pjungermann There is another issue, pointing out using $ref property under description: #1402
@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.
@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).
I think externalDocs should 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?
