Improve formatting of summaries in OpenAPI output
- 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
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