Repository navigation
externalDocs URL field needs a label #1760
Description
Here's my tags object in a non-trivial OpenAPI spec I'm writing:
tags:
- name: Providers
description: "Everything about Providers & other Organisations"
externalDocs:
description: "Provider & Staff Domain in SIF NZ data model"
url: http://localhost:8080/DomainMap.html#Domain__Provider
That URL turns up in Swagger-UI - but man it's ugly.
What I'd like to have is something like this:
tags:
- name: Providers
description: "Everything about Providers & other Organisations"
externalDocs:
description: "Provider & Staff Domain in SIF NZ data model"
link:
url: http://localhost:8080/DomainMap.html#Domain__Provider
label: SIF NZ Provider Domain
That way we get to render a proper <a href="localhost:8080/DomainMap.html#Domain_Provider">SIF NZ Provider Domain</a> link in Swagger UI etc.
PS: some of my deep links to external docs have non-english characters in them, so the URLs get even uglier: http://localhost:8080/DomainMap.html#Domain__StudentWh%C4%81nau
Activity
ioggstream commentedon Dec 21, 2018
Can't you
Your proposal would force all
urlto belink: {url: }handrews commentedon Oct 16, 2024
@stueynz (assuming you're still paying attention after all these years...) there is a proposal for 3.2 that adds a
summaryfield to the Tags Object, which would work for both inline descriptions andexternalDocs.Would that be sufficient? Alternatively, we could add a field to the External Docs Object, although it would be alongside the
urlfield rather than stuffing both it andurlunder another field (this is because we want 3.2 to be 100% backwards-compatible with 3.1).I estimate we'll publish 3.2 in Q1 2025 (I'd hoped for this year, but 3.0.4 and 3.1.1 have taken a bit longer to get out the door than planned).
github-actions commentedon Oct 23, 2024
This issue has been labeled with
No recent activitybecause there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.handrews commentedon Nov 20, 2024
this is only "not planned" in the sense of not doing a specific
labelfield for the External Documentation Object. The proposedsummaryfield is still slated for 3.2 and should address this use case.