Xref Link to For Swagger Rest API EndPoint

[groogiam]

I have api docs being generated from my json swagger definitions. I'm trying to figure how to add a link to a specific swagger api to a documentation article. I looked in the xrefmap.yml file and I can find an entry with a UID for the specific endpoint however it is generated with spaces.

- uid: Sandbox Framework API/2.8.0/UserProfile_UpdatePreferences
  name: UserProfile_UpdatePreferences

When I use this in an xref it does not resolve. Is there a way to work around this?

I have also tried just hard coding the link into my document but this results in a warning that that link does not exist because it is generated at build time.

Thanks.

[filzrev]

As far as I've tested on my environment.

Link to REST API page with uid work as expected even when space is contained at title.
(e.g. <xref:Swagger Petstore/1.0.0/createUser>)

Is it able to provide code that reproducible reported issue?

[groogiam]

@filzrev It does not work if you want to change the link title.

This works

<xref:Sandbox Framework API/2.8.0/UserProfile_UpdatePreferences>

but this does not

[User Profile Update Preferences API](xref:Sandbox Framework API/2.8.0/UserProfile_UpdatePreferences)

This results in [User Profile Update Preferences API](xref:Sandbox Framework API/2.8.0/UserProfile_UpdatePreferences) being output.

Thanks for your help.

[filzrev]

Thanks for providing example codes.
I can confirmed that problem is reproduced when using [title](xref:{uid}) syntax with UID that contain spaces.

I've confirmed this problem is resolved by using <xref:> syntax or escaping URL.

Examples links that works as expected

- [Title1](<xref:Swagger Petstore/1.0.0/createUser>)
- [Title2](xref:Swagger%20Petstore/1.0.0/createUser)
- [Title3](@Swagger%20Petstore/1.0.0/createUser)

Examples not working

- [BadLink1](xref:Swagger Petstore/1.0.0/createUser)
- [BadLink2](@"Swagger Petstore/1.0.0/createUser")

---

When using xref:{uid} syntax. It is treated as normal URL that have xref: protocol.
So if URL contains spaces. [title](xref:uid) will not be converted to link tag without URL escape.

When using <xref:{uid}> syntax. It's preprocessed by docfx markdig extension (XrefInlineExtension).
So in this case no need to escape URL.

[groogiam]

@filzrev This solves my issue. Thanks again for your help.

[groogiam]

@filzrev I'm running into a new issue in the latest version 2.76.0 where this links are generating warnings. The links in the generated site seem to work just fine so this warning seems like a bug. Any thoughts?

warning InvalidBookmark: Invalid link: '<a href="api/MyProject.OpenApi.Client.UserProfileClient.yml#MyProject_OpenApi_Client_UserProfileClient_UpdatePreferencesAsync">UserProfileClient.UpdatePreferencesAsync</a>'. The file api/MyProject.OpenApi.Client.UserProfileClient.yml doesn't contain a bookmark named 'MyProject_OpenApi_Client_UserProfileClient_UpdatePreferencesAsync'.

[filzrev]

@groogiam
What's docfx version works as expected before updated to 2.76.0?
And if possible. please provide minimum reproduceable files.

[groogiam]

@filzrev Nevermind. The issue was on my side. Thanks for the quick reply and sorry for the trouble.