OpenAPITools / OpenAPITools/openapi-generator

[REQ] Adding lamdas to improve docs generated files and to make them complying with Markdown rules

Open
#17,788 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

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

Many specification files contain fields that violate Markdown rules when generating OpenAPI documentation.

Describe the solution you'd like

I suggest introducing two lambda classes that modify these fields to improve the doc files:

  1. TidyLambda for the following changes :
  • Replace and normalize all non-standard apostrophes
  • Replace and normalize all non-standard quotes
  • Replace all HTML break tags with new lines
  • Escape all opening/closing brackets
  • Normalize spaces
  • Normalize new lines (maximum 2 consecutive line breaks)
  • Remove new lines at the end
  1. MakeSingleLineLambda for the following changes:
  • Convert any line breaks into a space

I opened a PR with my suggestion: https://github.com/OpenAPITools/openapi-generator/pull/17761

Describe alternatives you've considered

The specification files can be modified manually, but the code may have other uses beyond the md files.

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

Review the proposed implementation in PR #17761 first, then trace where generated OpenAPI Markdown documentation processes specification fields. Done means the two requested lambdas are integrated and their normalization behavior is covered for apostrophes, quotes, breaks, brackets, spaces, and newlines.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, markdown
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.