`externalDocs` support for the auto-generated PowerShell reference documents

[maisarissi]

1. Find a way of linking from the PowerShell reference page back to the API reference page.

2. Human written content in API reference page that describes the purpose of the cmdlet/api is not being migrated. Links also need to be migrated to PowerShell reference page.

• Extract the right information that we have in the API page:

• And than, use it as the first paragraph.

  The current information is being retrieved from the relationships session on the doc page:

3. Some parameters/properties are not bringing the right description from the API page. (Enum for sure, maybe others too)

• E.g., color in Update-MgUserCalendar (Update-MgUserCalendar - PowerShell Reference Docs // calendar resource type - Microsoft Graph Docs)

[georgend]

These all map to Operation descriptions in the OpenAPI: PATCH on a collection: Autogenerate description when DeepInsertSupport or DeepUpdateSupport is present. PATCH/PUT on a collection item: Use UpdateRestrictions.Description GET on a collection: Use ReadRestrictions.Description. GET on collection item: Use ReadRestrictions.ReadRestrictionByType.Description POST on a collection: InsertRestriction.Description DELETE on collection item: DeleteRestrictions.Description

OpenAPI PathItem descriptions are autogenerated and are used by the CLI tooling for things like e.g. mgc applications -h .

Relevant Capability Annotations: https://github.com/oasis-tcs/odata-vocabularies/blob/758e454f012dd50de1f96a51953054ead7ad4656/vocabularies/Org.OData.Capabilities.V1.md#ReadRestrictionsType https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#UpdateRestrictionsType

Actions:
@georgend to use ApiDoctor to inject from documentation into the CSDL metadata @irvinesunday to implement conversion to OpenAPI for operation descriptions in OpenApi.Net.OData library.

[maisarissi]

Hey @georgend . As part of our discussion, one of the things we want to investigate is whether is possible to use DevX API permissions endpoint (same endpoint used by @peombwa in the Find-MgGraphCommand) as part of our docs generation to fix https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/132.

[maisarissi]

Hi @georgend . As part of the ask I mentioned

Find a way of linking from the PowerShell reference page back to the API reference page.

I was talking to @darrelmiller about linking back to the API page as part of this effort, so I was wondering whether you are going to open a new PR in the APIDoctor to address it or update the existing one. Can you help me clarify it?

[darrelmiller]

Ping @georgend Getting this link into the metadata is going to drive a lot of downstream functionality. It is really important that we get this in ASAP.

[peombwa]

• [x] We should investigate if AutoREST supports links #1302.

[peombwa]

To have links supported in the command reference, the following prerequisites must be met first:

1. [x] ApiDoctor will need to inject the CSDL metadata with Links annotation. https://github.com/OneDrive/apidoctor/issues/114.
2. [x] OpenAPI.NET.OData will need to support converting the OData links annotation to OpenAPI externalDocs property of an operation object. https://github.com/microsoft/OpenAPI.NET.OData/issues/230. (July timeframe).
3. [ ] AutoREST.PowerShell will need to support externalDocs on an operation object. https://github.com/Azure/autorest.powershell/issues/960.