microsoftgraph/msgraph-cli

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

MIchaelMainer opened this issue · 8 comments

MIchaelMainer commented

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

image
calebkiage commented

This is the link in the metadata:

image

Maybe it's a metadata problem.

  • 👍1
ddyett commented

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

ddyett commented

follow up happening with Tooling Foundations to address metadata.

irvinesunday commented

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

image

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

  • 👍2
ddyett commented

@calebkiage please verify with latest build

calebkiage commented

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

image

irvinesunday commented

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

image

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 commented

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:

  • 👍1