倉庫指標
- 星標
- (3,783 顆星)
- PR 合併指標
- (PR 指標待抓取)
描述
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.
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.