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 #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]

• We should investigate if AutoREST supports links Find a way of linking from the PowerShell reference page back to the API reference page #1302.

[peombwa]

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

1. ApiDoctor will need to inject the CSDL metadata with Links annotation. Improve APIDoctor to get information from the docs and add them to the metadata using the right annotations OneDrive/apidoctor#114.
2. OpenAPI.NET.OData will need to support converting the OData links annotation to OpenAPI externalDocs property of an operation object. Add the documentation links from Links annotations in CSDL to OpenAPI Operations  microsoft/OpenAPI.NET.OData#230. (July timeframe).
3. AutoREST.PowerShell will need to support externalDocs on an operation object. [Feature Request] OpenAPI externalDocs on an operation object support Azure/autorest.powershell#960.