[BUG][Go] Multiline info.description is squished to a single line in the top of file comments

segevfiner commented 3 years ago

Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?
[x] Have you validated the input using an OpenAPI validator (example)?
[x] Have you tested with the latest master to confirm the issue still exists?
[x] Have you searched for related issues/PRs?
[x] What's the actual output vs expected output?
[ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

A multiline description that renders fine in swagger-ui is generated to the top every single file and squished to a single line when generated in the go generator. I expected it to preserve newlines. ~Also note that Go doc comments are not markdown, a truly complete solution would need to transform the CommonMark to the minimal syntax supported by Go to avoid unexpected rendering issues.~ - Not a godoc comment, just a top of file comment, not rendered by godoc.

openapi-generator version

v4.2.6 and feeeedd34d4f3a83501825d025502874f669a6bc (Docker image openapitools/openapi-generator-cli@sha256:4396b434b09f03c9cb9a20ff39f1406f13a9b224a25e77a41679cd993eb5c968)

OpenAPI declaration file content or url

openapi: '3.0.3'

info:
  title: Multiline Description
  version: 0.1.0
  description: |
    Paragraph #1

    Paragraph #2

    Paragraph #3

    1. Some
    2. List
    3. Of
    4. `Things`

paths: {}

Generation Details

docker run --rm \
  -v ${PWD}:/local openapitools/openapi-generator-cli@sha256:4396b434b09f03c9cb9a20ff39f1406f13a9b224a25e77a41679cd993eb5c968 generate \
  -i /local/openapi.yaml \
  -g go \
  -o /local/out/go

Steps to reproduce

Generate the provided schema for go.
Look at the comment at the top of the generated go files.

Related issues/PRs

Suggest a fix

auto-labeler[bot] commented 3 years ago

👍 Thanks for opening this issue! 🏷 I have applied any labels matching special text in your issue.

The team will review the labels and make any necessary changes.

garyfeltham commented 5 months ago

I believe we are having a similar issue potentially due to the org.openapitools.codegen.DefaultCodegen generating escaped notes from the description.

        op.unescapedNotes = operation.getDescription();
        op.notes = escapeText(operation.getDescription());

markdown-documentation/api.moustache

defines

{{summary}}{{#notes}}

    {{.}}{{/notes}}

our fix is to create a new template under markdown-documentation

{{summary}}{{#unescapedNotes}}

    {{.}}{{/unescapedNotes}}

and use as a template - see https://openapi-generator.tech/docs/templating/

We are experiencing a problem getting this picked up currently however it makes sense to where the issue lies.

hectorconceicao commented 5 months ago

I had a similar error and managed to fix it by using @garyfeltham's comment with a specific change. I overrode the following in the api_doc.mustache template for the target programming language.

Before:

{{summary}}{{#notes}}

    {{.}}{{/notes}}

After:

{{summary}}{{#notes}}

{{{unescapedNotes}}}{{/notes}}

From mustache documentation:

All variables are HTML escaped by default. If you want to return raw contents without escaping, use the triple mustache: {{{name}}}.

In the docker run to use a custom template we need to:

Create a volume -v ${ROOT}/src/main/docs/templates/Java:/local/CustomTemplate

specify template directory -t /local/CustomTemplate

OpenAPITools / openapi-generator