[BUG] [ASCIIDOC] Description of classes is not processed with asciidoc generator

[davvanbal]

We have some classes with tag annotations.

@Tag(name = "Service Name", description = "Description Text.")

We receive a generated yaml file with this information.

openapi: 3.0.1
...
tags:
- name: Service Name
  description: Description Text.
...

We use this file with the "asciidoc" Generator. Now we missing the "description" information in the output (the name is displayed).

The part of the template (index.mustache) looks like this:

== Endpoints

[.{{baseName}}]
=== {{baseName}}

{{{description}}}

{{#operation}}

...

{{{description}}} has no output.

== Endpoints

[.ServiceName]
=== ServiceName

[.methodname]
==== methodname

...

Tested with openapi-generator.version: 6.2.1 and 6.3.0

Are there any clues as to what we are doing wrong or is it a bug?

[corrigancd]

Have found a similar issue with the asciidoc generator, it seems to be affecting the format and description fields in the generated output. I think this is the template for that:

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/asciidoc-documentation/model.mustache

Here are the relevant OpenAPI file attributes:

openapi 3.0.0
...
    "samplingScriptId": {
        "$ref": "#/components/schemas/Keyword",
        "description": "testing description",
        "format": "keyword"
    },

Produces:

| Field Name| Required| Type| Description| Format
...
| samplingScriptId
| 
| String 
| 
|  

I think it should produce the below?

| Field Name| Required| Type| Description| Format
...
| samplingScriptId
| 
| String 
| testing description
| keyword

[corrigancd]

Follow up - in my case, it was possible to tidy up the documentation by removing nesting from the types. For example:

export interface User {
  id: number;
  email: string;
  name: string;
  status?: "Happy" | "Sad";
  phoneNumbers: string[];
  nested: {
    foo: string;
    /**
    * testing nested
    * @format string
    */
    bar: string;
  };
}

Produces:

I didn't realise that a nested type was created. In the example above, this is UserNested, which is not that intuitive for someone reading the docs imo.

But, a suitable fix (for my case) is to specify the nested type as its own type:

type Nested = {
  foo: string;
  /**
  * testing nested
  * @format string
  */
  bar: string;
}

export interface User {
  id: number;
  email: string;
  name: string;
  status?: "Happy" | "Sad";
  phoneNumbers: string[];
  nested: Nested;
}

This produces the below, and avoids the unintuitive nested type name: