Example override for ref schema object not working and HTML operations direct links not working

[christianrowlands]

Describe the bug

Greetings. I have been using this AsyncAPI html-template for years now and it has made documentation creation very easy, so thank you for that!

I have a couple minor bugs that I want to report.

1. The example that I set for a field is not being used in the generated HTML when using a $ref to a schema.
2. The the HTML direct links are not working for the operations.

I have published my AsyncAPI HTML docs on public URL, so you can see both issues on that site.

For # 1, if you look at any of the Payload schemas, they all have a messageType field. A couple months ago I noticed that the override description and example stopped working. For example, with the GSM Record under the gsm_message operation, the messageType should be The type of message, must be GsmRecord. since that is what I set it to here in the yaml spec.

In addition, the example is also not being overridden as expected. I set it to GsmRecord here in the yaml spec but in the generated doc it shows up as string. Below is a screenshot of the linked generated HTML:

For # 2, here is a "direct link" to one of the operations. About 9 months ago this direct link worked, but at some (probably when I upgraded to a new version) the direct link stopped working: https://messaging.networksurvey.app/#operation-subscribe-nr_message

Once on the page, you can click any of the operations or any of the messages on the side bar and it does not take you to the appropriate section. However, all the "Schema" links work as expected.

How to Reproduce

For reproducing the issue, you can either use the full yaml spec I have linked to that is in my GitHub repo, or you can use this condensed version I made below. I typically use the docker container for asyncapi to generate the yaml. Something like:

docker run --rm -it -v ${PWD}/asyncapi/test.yaml:/app/test.yaml -v ${PWD}/testdoc:/app/output asyncapi/generator:1.15.1 /app/test.yaml @asyncapi/[email protected] -o /app/output --force-write

asyncapi: 2.6.0
info:
  title: Test API
  version: 0.13.1
  description: >
    A test doc for reproducing an issue
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
servers:
  mosquitto:
    url: 'mqtt://test.mosquitto.org'
    protocol: mqtt
defaultContentType: application/json
channels:
  gsm_message:
    description: >-
      The gsm_message topic/channel is where GSM survey records can be
      published. For MQTT, set the MQTT topic as "gsm_message" and then publish
      a JSON message representing a GSM survey record in the format defined
      below.
    publish:
      message:
        $ref: '#/components/messages/gsmRecord'
components:
  messages:
    gsmRecord:
      name: GsmRecord
      title: GSM Record
      summary: >-
        Represents information recorded about a GSM tower at a particular time
        and geographic location.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/gsmRecordPayload'
  schemas:
    gsmRecordPayload:
      type: object
      required:
        - version
        - messageType
        - data
      properties:
        version:
          $ref: '#/components/schemas/version'
        messageType:
          $ref: '#/components/schemas/messageType'
          description: 'The type of message, must be GsmRecord.'
          example: GsmRecord
        data:
          type: object
          description: The payload of this message that contains all the message data.
          required:
            - deviceTime
          properties:
            deviceTime:
              $ref: '#/components/schemas/deviceTime'
    version:
      type: string
      description: >-
        The version number of the Network Survey Messaging API that this message
        is based off of.
      example: 0.13.1
    messageType:
      type: string
      description: >-
        The type of this message. This value must match the message name or the
        message will not be interpreted correctly.
    deviceTime:
      type: string
      format: date-time
      description: >-
        The timestamp of when this message was created in milliseconds formatted
        as an [RFC3339
        date-time](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
        For example, `'1996-12-19T16:39:57-08:00'`.

Expected behavior

The expected behavior is

1. That the messageType value in the generated example json code block should have a value of GsmRecord.
2. That the messageType description for GSM Record should be The type of message, must be GsmRecord.
3. That the HTML direct links for the operations and messages should take you to the appropriate section, not the top of the page.

Thanks again for creating this html-template and let me know if you need any more details or examples.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[christianrowlands]

FWIW I went back to an older version of the generator and html-template and I was at least able to get the example and description overrides to work:

docker run --rm -it -v ${PWD}/src/main/asyncapi/test.yaml:/app/test.yaml -v ${PWD}/testdoc:/app/output asyncapi/generator:1.9.12 /app/test.yaml @asyncapi/[email protected] -o /app/output --force-write.

[derberg]

@christianrowlands thanks for the issue and apologies for delay in answering. We were super focused on shipping AsyncAPI v3.

So if I understand there are 2 separate issues:

• one is anchors for operations. I think it is the same as Anchors for operations are not working as expected asyncapi-react#822. So let us consider this one as duplicate, expecialy that fix anyway can be provided only in asyncapi-react
• problem with messageType:
  • you cannot use other properties with $ref as they are basically ignored and removed

        messageType:
          $ref: '#/components/schemas/messageType'
          description: The type of message, must be GsmRecord.
          example: "GsmRecord"
    

    should be

        messageType:
          $ref: '#/components/schemas/messageType'
    

    and later messageType in line 1840 should look like this

    messageType:
      type: string
      description: The type of this message. This value must match the message name or the message will not be interpreted correctly.
      example: "GsmRecord"
    

    and all will be good 😄

Pro tip, maybe consider to use message examples feature from AsyncAPI instead providing example inside the schema. Advantage is you can store them separately and also have multiple examples.

[christianrowlands]

Thank you for the update @derberg.

I went ahead and tried out the latest version that was dropped for html-template (2.1.0), and noticed that the fix in the pr asyncapi/asyncapi-react#887 was released in version 1.2.13 of asyncapi/asyncapi-react as mentioned in this comment.

Thank you @jonaslagoni for fixing that bug!

I will try generating the docs again with html-template once version 2.1.1 (or 2.2.0) is released.

Note: This comment also applies to this issue (mentioning it here to keep the tickets linked since they overlap).

[christianrowlands]

Since I originally put two bugs in this one issue, and that is generally a bad practice, I went ahead and split it out into two issues. I moved the override $ref bug in the new issue here.

That will allow this issue to be closed once the html-template starts referencing version 1.2.13 of asyncapi/asyncapi-react.