externalDocs URL field needs a label

[stueynz]

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

[ioggstream]

Can't you

description: ...
url: ...
x-label: ...

Your proposal would force all url to be link: {url: }

[handrews]

@stueynz (assuming you're still paying attention after all these years...) there is a proposal for 3.2 that adds a summary field to the Tags Object, which would work for both inline descriptions and externalDocs.

Would that be sufficient? Alternatively, we could add a field to the External Docs Object, although it would be alongside the url field rather than stuffing both it and url under 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[bot]]

This issue has been labeled with No recent activity because 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]

this is only "not planned" in the sense of not doing a specific label field for the External Documentation Object. The proposed summary field is still slated for 3.2 and should address this use case.