Markdown immediately after SGML comment is not displayed properly by Swagger editor

[eric-murray]

Problem description
The Swagger editor ignore the markdown header directive following an SGML comment, e.g.:

<!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
# Authorization and authentication

Expected behaviour
Swagger editor will display the header line properly if there is a preceding blank line, e.g.:

<!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->

# Authorization and authentication

Alternative solution
The API bundling process could remove all SGML headers from releases

Additional context
Redoc displays properly, but is not affected by the additional blank line

[hdamker]

@eric-murray do have concrete API examples I can use to investigate? Which swagger-ui/editor version do you have used? (so all the usual data to reproduce the bug).

[hdamker]

@eric-murray I could see the effect in Swagger UI with ReleaseTest/r1.3/code/API_definitions/sample-service.yaml. CommonMark appears to allow the current form, but Swagger Editor’s Markdown renderer does not handle it as expected. The blank line is a robust workaround and harmless for other renderers.

Next steps:

• Changing the validation check to already now tolerate the additional blank lines (if enforced at all) -> APIs can fix the behavior already now
• Update the common file here in Commonalities WIP
• But the distribution into the repositories will happen only when Commonalities publish a new (patch) release and the repos update to it
  • This process can potentially supported by some automated PRs: replace r4.3 with r4.4 in release-plan.yaml and one which updates the text blocks ... order of merge would not matter together with the first step.
• Change the validation check again, now warning when the additional lines are missing

[hdamker]

Short update: the current validation checks allow already blank line before and after the delimiting HTML comments. No change of the check code was necessary for the first step, camaraproject/tooling#354 is just adding regression tests to ensure that this behavior gets not broken.

So: every API can already now use the blank lines to make Swagger editor/UI happy without triggering the validation. And after a change of the common template the validation will also not raise findings ... except we implement that explicitly.