swagger-api / swagger-api/swagger-codegen-generators
Use unescapedAppDescription in README files (to support specs with markdown descriptions)
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 299
- Forks
- 439
- PR merge metrics
- No merged PRs in 30d
Description
Hello,
In my group's openapi spec, we've written a fairly length markdown description for our api. However, when swagger-codegen puts that description into a README.md file, it has gone through some escaping, and, critically, all of the newlines have been removed, making it un-renderable as markdown.
However, it looks like there's also an unescapedAppDescription variable available. So my proposal here would be to use the unescapedAppDescription instead of the escaped appDescription in all of the README.md files.
To maintain backward compatibility, and/or to provide configurability, perhaps there should be a property/config for this? e.g., useUnescapedAppDescription?
I would be able & willing to make this change (in fact, I almost submitted a PR, but then read the guidelines which suggested opening an issue first). Please advise if this would be accepted. e.g.
{{#unescapedAppDescription}}{{{.}}}{{/unescapedAppDescription}}
{{^unescapedAppDescription}}{{#appDescription}}{{{.}}}{{/appDescription}}{{/unescapedAppDescription}}
Thanks!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the README.md templates that currently use appDescription and compare them with the available unescapedAppDescription variable. Review the proposed Mustache conditional and determine whether the change should be unconditional or configurable while preserving existing output. Done means markdown descriptions retain their formatting without unintentionally breaking existing README generation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100