swagger-api / swagger-api/swagger-codegen
Markdown supported in swagger-editor but not swagger-codegen
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
I can use Markdown in several places in my API spec (in YAML) to enter detailed descriptions, and swagger-editor will interpret it and display it correctly. However, when I put the resulting spec (in JSON) into swagger-codegen, it doesn't convert the markdown while generating a static HTML page. As far as I can tell, swagger-codegen doesn't accept YAML, so the end result is that I have to do extensive reformatting to convert my spec to HTML documentation. This has to be fixed.
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
Start by tracing swagger-codegen's static HTML documentation generation and compare its handling of Markdown with swagger-editor's rendering of the same JSON API specification. Done means Markdown in API descriptions is rendered correctly in the generated HTML without requiring manual reformatting; the payload names no specific files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100