CSharp - Path Parameters should keep their name and descriptions

[pillowfication]

Using the OpenAPI 3.0.0 petstore sample

kiota generate -d "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" -l CSharp

The part of interest is

"paths": {
  "/pets/{petId}": {
    "get": {
      "parameters": [
        {
          "name": "petId",
          "in": "path",
          "required": true,
          "description": "The id of the pet to retrieve",
          "schema": {
            "type": "string"
          }
        }
      ]
    }
  }
}

Current Behavior

The following block of code is created for the indexer

/// <summary>Gets an item from the ApiSdk.pets.item collection</summary>
public WithPetItemRequestBuilder this[string position] { get {
    var urlTplParams = new Dictionary<string, object>(PathParameters);
    if (!string.IsNullOrWhiteSpace(position)) urlTplParams.Add("petId", position);
    return new WithPetItemRequestBuilder(urlTplParams, RequestAdapter);
} }

Expected Behavior

I would like for the position variable to be named the same as the path parameter petId. I would also like for path parameter's description to be kept and placed in a corresponding <param/> documentation.

/// <summary>Gets an item from the ApiSdk.pets.item collection</summary>
/// <param name="petId">The id of the pet to retrieve</param>
public WithPetItemRequestBuilder this[string petId] { get {
    var urlTplParams = new Dictionary<string, object>(PathParameters);
    if (!string.IsNullOrWhiteSpace(petId)) urlTplParams.Add("petId", petId);
    return new WithPetItemRequestBuilder(urlTplParams, RequestAdapter);
} }

[baywet]

Thanks for your interest in kiota and for reporting this.

This is something that could be easily fixed by adding a ParameterDescription property on the code indexer DOM element and populating that property.

kiota/src/Kiota.Builder/KiotaBuilder.cs

Line 973 in 9f3c55f

return new CodeIndexer

kiota/src/Kiota.Builder/CodeDOM/CodeIndexer.cs

Line 4 in 9f3c55f

public class CodeIndexer : CodeTerminal, IDocumentedElement, IDeprecableElement

Then we need to make sure we carry the information when we convert the indexer to a method in other languages

kiota/src/Kiota.Builder/CodeDOM/CodeMethod.cs

Line 83 in 9f3c55f

ArgumentNullException.ThrowIfNull(originalIndexer);

And lastly we need to make sure we write the information in dotnet (the other languages will rely on the code parameter information already)

kiota/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs

Line 15 in 9f3c55f

conventions.WriteShortDescription(codeElement.Documentation.Description, writer);

Is this something you'd be willing to submit a pull request for?

[sebastienlevert]

@baywet Please review based on the 1.5 release improvements. Thanks!

[baywet]

The 1.5 improvements didn't impact this issue much: We now support type specific indexer parameters (not just string anymore, but also int etc...). #2594
We can't change the parameter name, it'd be a breaking change even though it's unlikely anybody has a direct reference to it. I created #3070 to follow up on this during v2.
We should still carry on the description of the parameter for a better developer experience. I'll work on that for the next release.