Test PowerShell integration with `Microsoft.OpenAPI.OData - v1.0.10-preview2` lib.

[irvinesunday]

The Microsoft.OpenAPI.OData - v1.0.10-preview2 OData - OpenAPI conversion lib. is out!
We need to test how this lib. integrates with PowerShell through DevX API via this test url: https://devxapitest.azurewebsites.net/ and bump up the lib version in this repo if successful.

[peombwa]

Here are the results from the first test with PowerShell SDK:

• All but three modules build after adding directives to fix circular references and broken commands
• DeviceManagement.Functions fails because we are using content instead of schema in the parameter object for GET /deviceManagement/microsoft.graph.getRoleScopeTagsByIds(ids=@ids) operation.
  
  AutoREST.PowerShell doesn't support parameter objects with content. In this case, there is no need for a content-type in a parameter. The ideal parameter object should be:

  /deviceManagement/microsoft.graph.getRoleScopeTagsByIds(ids=@ids):
    get:
      tags:
        - deviceManagement.Functions
      summary: Invoke function getRoleScopeTagsByIds
      operationId: deviceManagement_getRoleScopeTagsByIds
      parameters:
        - name: ids
          in: query
          description: 'Usage: ids={ids}'
          required: true
          schema:
            type: array
            items:
              type: string
        ...

• Sites and Files timeout after 8+ hours due to the number of paths and schemas. We will need to review the paths individually and remove those that are invalid.
  • Sites
    • v1.0

        ➜ hidi validate --openapi .\v1.0\Sites.yml
        Path Items: 715
        Operations: 1257
        Parameters: 7309
        Request Bodies: 388
        Responses: 1257
        Links: 1558
        Callbacks: 0
        Schemas: 11632

    • beta

        ➜ hidi validate --openapi .\beta\Sites.yml
        Path Items: 507
        Operations: 880
        Parameters: 4521
        Request Bodies: 282
        Responses: 880
        Links: 1069
        Callbacks: 0
        Schemas: 9820

  • Files
    • v1.0

        ➜ hidi validate --openapi .\v1.0\Files.yml
        Path Items: 546
        Operations: 1102
        Parameters: 4190
        Request Bodies: 384
        Responses: 1102
        Links: 979
        Callbacks: 0
        Schemas: 8018

    • beta

        ➜ hidi validate --openapi .\beta\Files.yml
        Path Items: 733
        Operations: 1409
        Parameters: 5435
        Request Bodies: 489
        Responses: 1409
        Links: 1640
        Callbacks: 0
        Schemas: 11174

[peombwa]

@irvinesunday, from my local test, the number of operations in Sites and Files can be substantially reduced by suppressing unwanted duplicate/invalid paths in the metadata (~1000 operations in v1.0 & beta), e.g.:

• /sites/{site-id}/lists/{list-id}/activities is readonly, we shouldn't generate CUD operations.
• /sites/{site-id}/lists/{list-id}/activities/{itemActivityOLD-id}* are all invalid. You can only list recent activities on a list, listItem, drive, & driveItem.
• Plus, all the paths in Add Explode attribute to specific nav properties msgraph-metadata#105 with explode=false.

Are we in a position to use microsoftgraph/msgraph-metadata#105 (as a namespaced annotation) in 1.0.10 or should we fall back to containsTarget=false?

[irvinesunday]

Here are the results from the first test with PowerShell SDK:

• All but three modules build after adding directives to fix circular references and broken commands

• DeviceManagement.Functions fails because we are using content instead of schema in the parameter object for GET /deviceManagement/microsoft.graph.getRoleScopeTagsByIds(ids=@ids) operation.
  
  AutoREST.PowerShell doesn't support parameter objects with content. In this case, there is no need for a content-type in a parameter. The ideal parameter object should be:

  /deviceManagement/microsoft.graph.getRoleScopeTagsByIds(ids=@ids):
    get:
      tags:
        - deviceManagement.Functions
      summary: Invoke function getRoleScopeTagsByIds
      operationId: deviceManagement_getRoleScopeTagsByIds
      parameters:
        - name: ids
          in: query
          description: 'Usage: ids={ids}'
          required: true
          schema:
            type: array
            items:
              type: string
        ...

• Sites and Files timeout after 8+ hours due to the number of paths and schemas. We will need to review the paths individually and remove those that are invalid.

  • Sites

    • v1.0

        ➜ hidi validate --openapi .\v1.0\Sites.yml
        Path Items: 715
        Operations: 1257
        Parameters: 7309
        Request Bodies: 388
        Responses: 1257
        Links: 1558
        Callbacks: 0
        Schemas: 11632

    • beta

        ➜ hidi validate --openapi .\beta\Sites.yml
        Path Items: 507
        Operations: 880
        Parameters: 4521
        Request Bodies: 282
        Responses: 880
        Links: 1069
        Callbacks: 0
        Schemas: 9820

  • Files

    • v1.0

        ➜ hidi validate --openapi .\v1.0\Files.yml
        Path Items: 546
        Operations: 1102
        Parameters: 4190
        Request Bodies: 384
        Responses: 1102
        Links: 979
        Callbacks: 0
        Schemas: 8018

    • beta

        ➜ hidi validate --openapi .\beta\Files.yml
        Path Items: 733
        Operations: 1409
        Parameters: 5435
        Request Bodies: 489
        Responses: 1409
        Links: 1640
        Callbacks: 0
        Schemas: 11174

The content in the parameter property for the DeviceManagement.Functions was added in this PR.
@baywet's initial schema proposal was similar to @peombwa's, as seen in this issue.

@darrelmiller is your initial proposal still valid in light of the above?

[baywet]

@irvinesunday the issue you linked refers to the return type conversion, not necessarily the parameters although the example is similar.

[irvinesunday]

@irvinesunday the issue you linked refers to the return type conversion, not necessarily the parameters although the example is similar.

Really?
Check out this fix:

I believe this is what added the content property in the parameter object

[baywet]

ah! I missing the content aspect during the PR review, my bad...

[irvinesunday]

ah! I missing the content aspect during the PR review, my bad...

It was suggested in @darrelmiller's proposal.

[irvinesunday]

@irvinesunday, from my local test, the number of operations in Sites and Files can be substantially reduced by suppressing unwanted duplicate/invalid paths in the metadata (~1000 operations in v1.0 & beta), e.g.:

• /sites/{site-id}/lists/{list-id}/activities is readonly, we shouldn't generate CUD operations.
• /sites/{site-id}/lists/{list-id}/activities/{itemActivityOLD-id}* are all invalid. You can only list recent activities on a list, listItem, drive, & driveItem.
• Plus, all the paths in Add Explode attribute to specific nav properties msgraph-metadata#105 with explode=false.

Are we in a position to use microsoftgraph/msgraph-metadata#105 (as a namespaced annotation) in 1.0.10 or should we fall back to containsTarget=false?

@peombwa
We should fall back to ContainsTarget=false
I have updated the https://devxapitest.azurewebsites.net/ endpoint with your recommendations of the containments to be removed. Please try the Files and Sites modules again to validate whether this change might have improved things.

[peombwa]

@irvinesunday, has https://devxapitest.azurewebsites.net/ been updated? The diff yields no change in the OpenAPI docs (files and sites).

[irvinesunday]

Sorry @peombwa I forgot to update the updated metadata url in the https://devxapitest.azurewebsites.net/ app service. It should be good now.