microsoft/kiota

Description fields overshadow Summary fields

オープン

#2,979 opened on 2023/07/21

 (1 件のコメント) (0 件のリアクション) (1 人の担当者)C# (326 件のフォーク)auto 404
enhancementgeneratorhelp wanted

Repository metrics

Stars
 (3,783 個のスター)
PR merge metrics
 (PR metrics pending)

説明

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.

コントリビューターガイド