OpenAPI.NET.OData: Semantic violation: Certain OData functions have path parameters referenced in query

Certain OData functions have path parameters referenced in query instead of path. This results in generation error since code generators cannot find the specified path parameters.

Current Representation

'/users/{user-id}/joinedTeams/{team-id}/primaryChannel/microsoft.graph.doesUserHaveAccess(userId=''{userId}'',tenantId=''{tenantId}'',userPrincipalName=''{userPrincipalName}'')':
  get:
    tags:
      - users.Functions
    summary: Invoke function doesUserHaveAccess
    operationId: users.joinedTeams.primaryChannel_doesUserHaveAccess
    parameters:
      - name: user-id
        in: path
        description: 'key: id of user'
        required: true
        schema:
          type: string
        x-ms-docs-key-type: user
      - name: team-id
        in: path
        description: 'key: id of team'
        required: true
        schema:
          type: string
        x-ms-docs-key-type: team
      - name: userId
        in: query
        description: 'Usage: userId=''{userId}'''
        schema:
          type: string
          nullable: true
      - name: tenantId
        in: query
        description: 'Usage: tenantId=''{tenantId}'''
        schema:
          type: string
          nullable: true
      - name: userPrincipalName
        in: query
        description: 'Usage: userPrincipalName=''{userPrincipalName}'''
        schema:
          type: string
          nullable: true
    responses:
      '200': ...
      default:
        $ref: '#/components/responses/error'
    x-ms-docs-operation-type: function

Ideal Representation

'/users/{user-id}/joinedTeams/{team-id}/primaryChannel/microsoft.graph.doesUserHaveAccess(userId=''{userId}'',tenantId=''{tenantId}'',userPrincipalName=''{userPrincipalName}'')':
  get:
    tags:
      - users.Functions
    summary: Invoke function doesUserHaveAccess
    operationId: users.joinedTeams.primaryChannel_doesUserHaveAccess
    parameters:
      - name: user-id
        in: path
        description: 'key: id of user'
        required: true
        schema:
          type: string
        x-ms-docs-key-type: user
      - name: team-id
        in: path
        description: 'key: id of team'
        required: true
        schema:
          type: string
        x-ms-docs-key-type: team
      - name: userId
+         in: path
-         in: query
        description: 'Usage: userId=''{userId}'''
        schema:
          type: string
          nullable: true
      - name: tenantId
+         in: path
-         in: query
        description: 'Usage: tenantId=''{tenantId}'''
        schema:
          type: string
          nullable: true
      - name: userPrincipalName
+         in: path
-         in: query
        description: 'Usage: userPrincipalName=''{userPrincipalName}'''
        schema:
          type: string
          nullable: true
    responses:
      '200': ...
      default:
        $ref: '#/components/responses/error'
    x-ms-docs-operation-type: function

About this issue

Original URL
State: closed
Created 2 years ago
Comments: 25 (16 by maintainers)

Most upvoted comments

After some more thinking with Darrel, here is what we came up with:

required parameters should be path parameters in the open API description, unaliased
optional parameters should be explicitly aliased, and be query parameters in the open API description

The case where function overloads have the same required parameters but vary in optional parameters is a non-existing case as the OData engine would not know which overload to pick when not providing all parameters (impossible to implement on the service side).

A few Open API path items examples

path/foo(param1='{param1}') (param1 required and in path, no optional parameters) path/foo(param1='{param1}',param2='@param2') (param1 required and in path, param2 optional and in query) path/foo(param1='@param1') (no required parameter, param1 optional and in query)

Note : {?param1} or {?param2} will be added to the URL template by kiota when generating the client, not the conversion process.

baywet on Sep 2, 2022

Are we going with implicit parameter aliases with the format? /roleManagement/directory/microsoft.graph.roleScheduleInstances?directoryScopeId={directoryScopeId}&appScopeId={appScopeId}&principalId={principalId}&roleDefinitionId={roleDefinitionId}

irvinesunday on Aug 30, 2022

still the parameters should be in path and not in query, this is something we’re running into in Kiota based SDK as well.

baywet on Aug 18, 2022