How to insert introduction to generated api docs

[wutz]

Is this a BUG REPORT or FEATURE REQUEST?:

/kind feature

What you expected to happen:

Before to use api, user need to known about general information, like how to Authentication.

[kdada]

Write your description to nirvana.yaml.

[wutz]

Write to description ? I may be write more than one paragraph.

[wutz]

May be like https://docs.docker.com/engine/api/v1.25/ to provide multiple section, example: Errors, Versioning and Authentication.

[kdada]

YAML supports multi-lines string:

description: |
  Write your description here.
  This is the second paragraph.

[kdada]

/kind support

[wutz]

I'm refer to https://github.com/Rebilly/ReDoc/blob/master/demo/swagger.yaml, but line start with # can not display as a heading, it just display as origin.

description: |
  The description here.
  # Introduction
  The introduction here.

[wutz]

I have notice that the new line of description which in nirvana.yaml have been generated as \u003cbr/\u003e (<br/>).

If i change the new line of generated openapi spec json from <br/> to \n, then # introduction can display heading correctly.

[wutz]

https://github.com/caicloud/nirvana/blob/e559644a421467a6d682b8d3cd056c974f9cee77/utils/generators/swagger/generator.go#L529-L531

@kdada Why replace \n to <br/> ?

[kdada]

@wutzx

If not escape newline, two line will be merged into one line in markdown. It seems that we should not replace the newline character.

[kdada]

/kind bug