dotnet / dotnet/aspnetcore

Improve formatting of summaries in OpenAPI output

Open
#67,992 3 comments 3 reactions 0 assignees View on GitHub
area-minimal feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

Microsoft.AspNetCore.OpenApi output could be more helpful in how summaries are formatted in the output.

By comparison, Swashbuckle produces this:

```yaml
description: "\nParagraph one.\n\nParagraph two."
```

Microsoft.AspNetCore.OpenApi produces this:

```yaml
description: " Paragraph one.\r\n Paragraph two."
```

We can observe the following differences:
1. Microsoft.AspNetCore.OpenApi separates paragraphs by a single line instead of two.
2. Microsoft.AspNetCore.OpenApi emits an OS-specific line separator.
3. Microsoft.AspNetCore.OpenApi emits the original summary's indentation.
4. _Swashbuckle emits a leading `\n`, which is somewhat surprising, but does not seem to get in the way._

### Describe the solution you'd like

Proposal:
1. A single line is a poor paragraph separator. The readability leaves a lot to be desired. Let's use two lines, like Swashbuckle does.
2. The OS-specific line separators are a hindrance in tests. Let's use `\n` consistently.
3. The indentation is distracting at best and distorting at worst (if ever used in a context where it shows up). Let's remove it.

### Additional context

_No response_

Contributor guide

Open the contributing guide

Research direction

No file or test is named in the issue. Start by locating the Microsoft.AspNetCore.OpenApi code that formats endpoint summaries and its existing OpenAPI output tests, then compare the current output with the Swashbuckle example. Done means paragraph breaks use two lines, line endings are consistently \n, and source indentation is removed.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, openapi
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.