[V1 RC Bug Bash]: Incorrect documentation links in `mgc users -h`

[MIchaelMainer]

I needed to get information about permissions. Followed the doc links for /users and got the incorrect document for my use case.

[calebkiage]

This is the link in the metadata:

Maybe it's a metadata problem.

[ddyett]

let's follow up this one with the metadata team. This likely would be an issue for powershell as well.

[ddyett]

follow up happening with Tooling Foundations to address metadata.

[irvinesunday]

From the latest OpenAPI description, the /users endpoint seems to have the correct documentation link:

Ref: https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml

[ddyett]

@calebkiage please verify with latest build

[calebkiage]

@irvinesunday, it seems the link has changed to a different one this time. see microsoftgraph/msgraph-metadata v1.0 openapi.yaml

[irvinesunday]

@irvinesunday, it seems the link has changed to a different one this time. see microsoftgraph/msgraph-metadata v1.0 openapi.yaml

Thanks for surfacing this @calebkiage

The url changed from https://learn.microsoft.com/en-us/graph/api/user-list?view=graph-rest-1.0 to https://learn.microsoft.com/en-gb/graph/api/intune-onboarding-user-list?view=graph-rest-1.0

@millicentachieng can you help look into API doctor and see what might have changed in the process of scraping descriptions for users?

[millicentachieng]

There are common endpoints between the regular Graph and Intune, documented separately in different API topics, e.g. /users, /users/{id}, /organization, and /organization/{id}.

While the API Doctor process remains unchanged, Intune has recently introduced additional metadata to their documentation aiming to facilitate code snippets injection through API Doctor. Consequently, API Doctor now extracts descriptions and documentation links from these updated Intune docs. In cases where multiple documentation entries are present for an endpoint, API Doctor selects the first item on the list, which happens to be Intune in this scenario.

We've observed that this has impacted various tools, including the links on Graph Explorer. There's an ongoing discussion about the optimal approach to manage documentation and metadata for shared endpoints. One proposed solution is to merge all API topics that refer to the same endpoint to streamline the information.

Example:

• https://learn.microsoft.com/en-us/graph/api/user-list?view=graph-rest-1.0&tabs=http
• https://learn.microsoft.com/en-us/graph/api/intune-mam-user-list?view=graph-rest-1.0&tabs=http