microsoft / microsoft/kiota

Description fields overshadow Summary fields

Open
#2,979 1 comment 0 reactions 1 assignee Claimed by @pillowfication View on GitHub
enhancement generator help wanted
Dominant language
C#
Stars
3.8k
Forks
333
Avg merge
16h 29m
Merged PRs (30d)
116

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](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.

```json
"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.

```csharp
///
/// Make sure you get a Foo first
///
public async Task 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 `` and `` tags that can house the two fields.

```csharp
///
/// Get a Bar
///
///
/// Make sure you get a Foo first
///
public async Task GetAsync() { }
```

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

```java
/**
* Get a Bar
*


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

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.