asyncapi/html-template

For Avro payload format, if examples message is specified in yaml, html generator fails

jyotibhangale opened this issue · 8 comments

jyotibhangale commented

Describe the bug

For Avro payload format, if examples block is specified in yaml, html generator fails with error

How to Reproduce

ag .\user_signedup.yaml @asyncapi/html-template

Something went wrong:
Error: There were errors validating the AsyncAPI document.
at parse (C:\Users\jyotibhangale\AppData\Roaming\npm\node_modules@asyncapi\generator\node_modules@asyncapi\parser\lib\parser.js💯23)
at Generator.generateFromString (C:\Users\jyotibhangale\AppData\Roaming\npm\node_modules@asyncapi\generator\lib\generator.js:265:22)
at C:\Users\jyotibhangale\AppData\Roaming\npm\node_modules@asyncapi\generator\cli.js:154:9
[
{
"title": "/channels/transactions/subscribe/message should have required property '$ref'",
"location": {
"jsonPointer": "/channels/transactions/subscribe/message",
"startLine": 22,
"startColumn": 7,
"startOffset": 623,
"endColumn": null
}
},
{
"title": "/channels/transactions/subscribe/message should NOT have additional properties",
"location": {
"jsonPointer": "/channels/transactions/subscribe/message/description",
"startLine": 23,
"startColumn": 9,
"startOffset": 641,
"endLine": 23,
"endColumn": 69,
"endOffset": 701
}
},

....

Expected behavior

Should generate html document from asyncapi spec.

github-actions commented

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.

magicmatatjahu commented

@jyotibhangale Hello. It's not a problem with html-template but with your AsyncAPI document. Extended examples with summary field is from 2.1.0 version of spec, and also examples are an array of object, not array of objects with one field (as id), so you should change your examples to the:

        examples:
          - name: payment
            summary: Example payment
            payload: |-
              {"id": "{{randomString(32)}}", "amount": {{randomInt(25, 50)}}}

shape. Also, please don't write payload as string (atm you write as string), but as object:

payload: 
  id: "{{randomString(32)}}"
  amount: {{randomInt(25, 50)}}

And most important, please change version of spec to 2.1.0, but better will be to the 2.2.0 :)

More info: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageExampleObject

magicmatatjahu commented

@jyotibhangale I will close issue, please reopen it if you have more questions/problems.

jyotibhangale commented

Hi @magicmatatjahu , Thank you for addressing my issue. although after making suggested changes I am still running into same error.
user_signedup.yaml:
....
payload:
$ref: './avro/Payment.avsc'
examples:
- name: payment
payload:
id: "{{randomString(32)}}"
amount: {{randomInt(25, 50)}}

magicmatatjahu commented

@jyotibhangale Did you change also the version of spec?

Here is a valid spec:

asyncapi: '2.2.0'
id: 'urn:io.confluent.examples.payment'
info:
  title: Payment Avro API
  version: 0.1.2
  description: Sample AsyncAPI for user signedup events defined using Avro
  contact:
    name: Shane Lee
    url: https://github.com/shavo007
    email: x@gmail.com
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
defaultContentType: application/json
tags:
  - name: payment
servers:
    production:
      url: broker.mycompany.com
      protocol: kafka
      description: This is "My Company" broker.
channels:
  transactions:
    description: The topic on which user signed up events may be consumed
    subscribe:
      summary: Receive informations about payments
      description: Hello
      operationId: receivedPayment
      message:
        description: An event describing that a user just signed up.
        bindings:
          kafka:
            key:
              type: string
              description: id of the payment
        contentType: avro/binary
        schemaFormat: application/vnd.apache.avro+json;version=1.9.0
        payload:
          $ref: './Payment.avsc'
        examples:
          - name: payment
            summary: Example payment
            payload:
              id: "{{randomString(32)}}"
              amount: "{{randomInt(25, 50)}}"

The problem may also be that you are using an old version of the generator/template. Please install the latest generator:

npm i -g @asyncapi/generator

and use the latest version of template:

ag <your-spec> @asyncapi/html-template@0.24.0 <rest>

Let me know if everything is good :)

jyotibhangale commented

using latest version of template did the trick, appreciate your help.

  • 👍1
jyotibhangale commented

Hi, also wanted to understand if I have multiple asyncapi specs and want to generate html documentation on single page, is that possible? I have to create individual directory for each spec.

magicmatatjahu commented

@jyotibhangale At the moment generator only can handle single AsyncAPI document, so we have a limit here. In some cases, like generating servers or server clients based on AsyncAPI, "generating" several specs does not make sense, but in case of html-templates and widely understood documentation templates (including markdown) such solution would make sense.

As far as I know, AsyncAPI 3.0.0 version will most probably have a possibility to define several applications against one document -> here more about it asyncapi/spec#658 Then we will also provide such possibility in html-template itself. If you would like such solution also for 2.X.X please create an issue in generator repository and describe the problem. I can't guarantee that we will implement such a thing, but we will remember about such use case :) Repo for generator https://github.com/asyncapi/generator