Handling of optional function parameters
- Dominant language
- C#
- Stars
- 3.8k
- Forks
- 333
- Avg merge
- 16h 29m
- Merged PRs (30d)
- 116
Description
Related to
- https://github.com/microsoft/OpenAPI.NET.OData/issues/259
- https://github.com/microsoft/OpenAPI.NET.OData/pull/195
- https://github.com/microsoft/OpenAPI.NET.OData/pull/272
According to the conversion library changes above, if a function has optional parameters, the parameter will be marked to be
`in: query` rather than `in: path`
example.
```yaml
/roleManagement/entitlementManagement/roleDefinitions/{unifiedRoleDefinition-id}/inheritsPermissionsFrom/{unifiedRoleDefinition-id1}/assignedPrincipals(transitive=@transitive,directoryScopeType=''@directoryScopeType'',directoryScopeId=''@directoryScopeId'')':
description: Provides operations to call the assignedPrincipals method.
get:
tags:
- roleManagement.Functions
summary: Invoke function assignedPrincipals
operationId: roleManagement.entitlementManagement.roleDefinitions.unifiedRoleDefinition.inheritsPermissionsFrom.unifiedRoleDefinition.assignedPrincipals
parameters:
- name: transitive
in: query
description: 'Usage: transitive=@transitive'
schema:
type: boolean
default: false
- name: directoryScopeType
in: query
description: 'Usage: directoryScopeType=''@directoryScopeType'''
schema:
type: string
- name: directoryScopeId
in: query
description: 'Usage: directoryScopeId=''@directoryScopeId'''
schema:
type: string
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
enum:
- id
- deletedDateTime
type: string
```
Kiota however interprets this as a query parameter and adds query options to
- the URL template e.g. `/roleDefinitions/{unifiedRoleDefinition%2Did}/assignedPrincipals(transitive=@transitive,directoryScopeType='@directoryScopeType',directoryScopeId='@directoryScopeId'){?transitive*,directoryScopeType*,directoryScopeId*,%24top,%24skip,%24search,%24filter,%24count,%24select,%24orderby}`
- QueryParameter object e.g https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet/blob/56ec7408c228ee8d1eb58add9510c21a96c0aeea/src/Microsoft.Graph/Generated/RoleManagement/CloudPC/RoleDefinitions/Item/AssignedPrincipalsWithTransitivedirectoryScopeTypeDirectoryScopeTypeDirectoryScopeIdDirectoryScopeId/AssignedPrincipalsWithTransitivedirectoryScopeTypeDirectoryScopeTypeDirectoryScopeIdDirectoryScopeIdRequestBuilder.cs#L77
As this is a function, this brings up a few points/queries.
- As the function has optional parameters. It would make sense to have overloads generated (depending on the language) with the parameters passed.
- Trying to call the function with (no parameter passed) would result in an invalid url as the template would resolve to calling the function with placeholders instead of them being omitted from the url completely. The url template generation needs to cater for this.
- If passing the optional parameters through the query parameters object works, this is not intuitive as the function segment in the SDK is generated without parameters and the experience would involve using the query parameter object. At the moment, the url template generation now would add the parameters to the query parameters as well.
If having optional parameters in the query is an Odata specific conversion issue and is not expected in `any` OpenAPI description that Kiota would consume, we may have to move this conversation to the conversion library.
cc @baywet @darrelmiller
Contributor guide
Research direction
Start with Kiota's URL-template generation and query-parameter handling, using the generated AssignedPrincipals...RequestBuilder.cs link in the issue as the concrete example. Determine how optional function parameters should be represented when omitted or supplied, and verify that generated URLs do not retain placeholders or duplicate parameters; no test file is named in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, openapi
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100