swagger-api / swagger-api/swagger-codegen-generators

Use unescapedAppDescription in README files (to support specs with markdown descriptions)

Open
#1,124 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.