microsoft/kiota

Description fields overshadow Summary fields

Ouverte

#2 979 ouverte le 21 juil. 2023

 (1 commentaire) (0 réaction) (1 personne assignée)C# (326 forks)auto 404
enhancementgeneratorhelp wanted

Métriques du dépôt

Stars
 (3 783 étoiles)
Métriques de merge PR
 (Métriques PR en attente)

Description

Some nodes in OpenAPI (e.g. the Path Item Object) can have both a summary field and a description field. Kiota will always use the description field if it exists, otherwise falling back to the summary field as the node's only description. While there seems to be a lot of variance in how these two fields are utilized, it would be nice if they were both retained somehow.

https://github.com/microsoft/kiota/blob/9f3c55fca68a0ec94abab7edcde0cc45463a9c67/src/Kiota.Builder/Extensions/OpenApiUrlTreeNodeExtensions.cs#L142

Current Behavior

A common paradigm is to use summary for short descriptions, and additionally add a description as a more detailed summary OR to supplement the summary with auxiliary details.

"paths": {
  "/foo": { "get": {
    "summary": "Get a Foo",
    "description": "Returns a high-quality, made-to-order Foo"
  } },
  "/bar": { "get": {
    "summary": "Get a Bar",
    "description": "Make sure you get a Foo first"
  } }
}

In this example, the generated docs for GET /bar become awkward.

/// <summary>
/// Make sure you get a Foo first
/// </summary>
public async Task<BarView?> GetAsync() { }

Expected Behavior

Ideally I would like both the summary and description to be preserved somehow, when they are both present. C# has both the <summary/> and <remarks/> tags that can house the two fields.

/// <summary>
/// Get a Bar
/// <summary>
/// <remarks>
/// Make sure you get a Foo first
/// </remarks>
public async Task<BarView?> GetAsync() { }

For languages like Java, the two fields can be concatenated.

/**
 * Get a Bar
 * <p>
 * Make sure you get a Foo first
 * @return a CompletableFuture of BarView
 */
@javax.annotation.Nonnull
public java.util.concurrent.CompletableFuture<BarView> get() { }

When only one of summary or description is used, the current behavior is fine.

Guide contributeur