asyncapi / generator Goto Github PK

When a channel has a description, it is not generated and printed in HTML.

See the following demo specification and use https://playground.asyncapi.io/

asyncapi: '2.0.0-rc1'
id: 'urn:demo'
info:
  title: Demo
  version: '1.0'

channels:

  demo/channel:
    description: The description of demo channel.
    publish:
      summary: Channel summary
      message:
        $ref: '#/components/messages/demoMessage'

components:

  messages:

    demoMessage:
      name: demoMessage
      payload:
        $ref: '#/components/schemas/demoHeader'

  schemas:

    demoHeader:
      type: object
      properties:
        id:
          type: string
          description: The id of the header
        name:
          type: string
          description: The name of the header

The npm package allows to set a file name for the generated file, the cli version doesn't have this flag. Would be very handy to support this option.

We should update the generator package so it works with AsyncAPI 2.0.0. It should not be backward compatible so AsyncAPI 1.x documents will not work.

Installed the latest version of asynapi-generator:
npm install -g asyncapi-generator

ran command:
ag test-wss-api.yaml markdown

get error:
/Users/xxx/.nvm/versions/node/v8.0.0/lib/node_modules/asyncapi-generator/lib/generator.js:352
...config,
^^^

SyntaxError: Unexpected token ...
at createScript (vm.js:74:10)
at Object.runInThisContext (vm.js:116:10)
at Module._compile (module.js:533:28)
at Object.Module._extensions..js (module.js:580:10)
at Module.load (module.js:503:32)
at tryModuleLoad (module.js:466:12)
at Function.Module._load (module.js:458:3)
at Module.require (module.js:513:17)
at require (internal/module.js:11:18)
at Object. (/Users/xxx/.nvm/versions/node/v8.0.0/lib/node_modules/asyncapi-generator/cli.js:7:18)

same error with:
ag -V

I would like to provide generator for stomp over sockjs AsyncAPI.
It would be useful for consuming Spring Stomp over SockJS APIs in node/browser env - especially in companion with swagger-generated typescript-fetch client.

Is there something I should be aware of before starting my work on it?

generator.js line 66
if (!templatesDir) this.templatesDir = DEFAULT_TEMPLATES_DIR;
this.templatesDir doesn't get populated when templatesDir is provided

should be something like:
this.templatesDir = templatesDir || DEFAULT_TEMPLATES_DIR;

I’ve tried to use slack's asyncapi definition with asyncapi-generator (v0.5.1) to generate markdown and it works fine, but when I try the one with the events , rather than topics , from your repo
https://github.com/asyncapi/asyncapi/blob/master/test/docs/slack-rtm.yml

It fails with an error:

Something went wrong:
TypeError: Cannot convert undefined or null to object
    at Function.keys (<anonymous>)
    at module.exports (C:\ … \npm\node_modules\as
yncapi-generator\lib\beautifier.js:163:43)
    at parse.then (C:\ :\ … \npm\node_modules\asynca
pi-generator\lib\generator.js:284:25)
    at process._tickCallback (internal/process/next_tick.js:68:7)

Online editor http://editor.asyncapi.org/ fails to parse it as well , with an error

Cannot convert undefined or null to object

The concept of events seems to be much more appealing in documenting our websockets api, would really like to make it work, not sure what’s am I missing? Is there any other tool I could use to generate the documentation?

Thanks.

It would be awesome to have the chance to generate Java/Scala code from the AsyncAPI spec. Not an expert in Java/Scala but by some quick research I found Akka to be the most popular. Please "javers" correct me if I'm wrong.

When your payload contains a nested object and you specify that there are required properties in the enveloping object, then the generated "required" text does not render in the correct location(s) or with the correct styling.

Why

This would allow generation of code (or documentation) based on input other than AsyncAPI document instances.

Example

If we had a JSON Schema front-end, we could (with suitable templates) automatically generate parsing code in multiple languages from the AsyncAPI schema instance.

Other code-generation templates could then depend on this lower-level parser, meaning it would be faster and more accurate to generate new parsing code whenever there was a schema change or correction.

This may be useful in order to support both AsyncAPI v1 and v2 anyway.

Wanted to request support for generating serde_json structures from asyncapi definitions.

Running 0.9.0, our A2S document was fine, but with 0.10.1 the generator just spews out:

Something went wrong:
Error: Invalid AsyncAPI document
    at parse (/usr/lib/node_modules/asyncapi-generator/node_modules/asyncapi-parser/lib/parser.js:93:11)
    at <anonymous>

After some debugging, it was clear that the root cause was a ' in a description element, as in the following example:

asyncapi: '2.0.0-rc1'
id: 'urn:hello-world-app'
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    description: "subscribe to hello's"
    subscribe:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

It's probably us not following the A2S spec (though I haven't been able to find anything that says it's not allowed), but could the generator be a bit more helpful as to why it failed?

Thanks

Based on the AsyncAPI specs, the topics property is optional as long as stream or events is used instead.

YAML to Reproduce

asyncapi: "1.2.0"
info:
  title: AsyncAPI Sample
  version: 1.0.0

servers:
  - url: domain:1234
    scheme: ws

events:
  send:
    - $ref: '#/components/messages/sendMessage'
  receive:
    - $ref: '#/components/messages/receiveMessage'

components:
  messages:

    sendMessage:
      payload:
        type: object
        properties:
          abcd:
            type: string

    receiveMessage:
      payload:
        type: object
        properties:
          efgh:
            type: string

Current Behaviour:
The "Topics" is displayed, even though, it is not used.

Expected Behaviour:
The "Topics" block is not rendered.

Hi,

We expect the tools handling the YAML file to adjust their engine according to the version of the specification defined in the file, not to target the upcoming, unreleased, latest version.

A file with the following version should be handled accordingly. Right now the generator renders empty files, without so much as a warning. This is very confusing.

asyncapi: 1.2.0

I installed a previous version to be able to work with the current version of the specification.

npm install -g [email protected]

Maybe we could mention this in the README.

When you have long examples, they take up so much space in the right column, that in the middle column there will be very much white space between one operation to the next.

The OpenApi html generator ReDoc solves this by folding the examples. The user is able to expand and collapse them.

The java-spring template partial AmqpConfig adds a comma when it is not the last topic.

When a situation occurs when the last topic is a subscribe topic the comma will be added to the generated source. This will cause a compile error.

Afaik handlebars can only solve this with a custom helper. Or by splitting the subscribe and publish topics into two different lists.

**Is your feature request related to a problem? No

Can't it be tackled using specification extensions?
No

Describe the solution you'd like
To allow a "example:" tag inside of the definition of the properties. The value associated to the "example" tag is the one that will be rendered in the "automatically generated payload" for those properties that do not have a "default" value. Notice that you can decide that there is no default value for a schema but however, you want to provide a complete example of such schema to the reader of the documentation. This is where the "example" (or any other better name) could help.

Describe alternatives you've considered
Read documentation and no alternatives foreseen.

Additional context
N/A

Why

• Arguably this would facilitate the setup for new users with little experience with npm
• have presence in docker hub

generate a docker file to host RabbitMQ to run applications using AMQP.

Hello,
i loved your talk. So i decided you to help on this. In embedded enviroment there is a lack of rest framework so this will open new scenarios.

Both the MqttConfig and AmqpConfig partial template files will currently result in a compiler error when a spec contains a topic object with a publish property.

In the MqttConfig template the setDefaultTopic function will be called with an undefined variable. Since the template only creates the corresponding private members if the topic is of type subscribe.

The same applies to the AmqpConfig template file where the setExchangeName function will be called with an undefined variable. Since the template only creates the corresponding private members if the topic is of type subscribe.

Hi, I'm trying to reference a json definition from one file to another in the same directory but when I execute the asyncapi-generator I get an error.

Folder Structure:

Inside push.json
"definitions": { "push-data": { "$ref": "file:../../../schema/v1/push/push-data.json" } }

I execute "node generate_html.js" inside the generator folder and I get this:

Can not dereference the JSON obtained from the content of the AsyncAPI specification file
{
"errno": -2,
"code": "ENOENT",
"syscall": "open",
"path": "/../../../schema/v1/push/push-data.json",
"name": "Error",
"message": "Error opening file "/../../../schema/v1/push/push-data.json"
ENOENT: no such file or directory, open '/../../../schema/v1/push/push-data.json'",
"stack": "Error: Error opening file "/../../../schema/v1/push/push-data.json"
ENOENT: no such file or directory, open '/../../../schema/v1/push/push-data.json'
at ReadFileContext.callback (/var/www/html/node_modules/json-schema-ref-parser/lib/resolvers/file.js:52:20)
at FSReqWrap.readFileAfterOpen [as oncomplete] (fs.js:242:13)
Error: ENOENT: no such file or directory, open '/../../../schema/v1/push/push-data.json'"
}
{
"errno": -2,
"code": "ENOENT",
"syscall": "open",
"path": "/../../../schema/v1/push/push-data.json",
"name": "Error",
"message": "Error opening file "/../../../schema/v1/push/push-data.json"
ENOENT: no such file or directory, open '/../../../schema/v1/push/push-data.json'",
"stack": "Error: Error opening file "/../../../schema/v1/push/push-data.json"
ENOENT: no such file or directory, open '/../../../schema/v1/push/push-data.json'
at ReadFileContext.callback (/var/www/html/node_modules/json-schema-ref-parser/lib/resolvers/file.js:52:20)
at FSReqWrap.readFileAfterOpen [as oncomplete] (fs.js:242:13)
Error: ENOENT: no such file or directory, open '/../../../schema/v1/push/push-data.json'"
}
(node:14770) [DEP0079] DeprecationWarning: Custom inspection function on Objects via .inspect() is deprecated

I tryed both "file:../" and "file://../".

Thank you.

Is your feature request related to a problem? Please describe.

Enumermations which are serialized as integer have no meaning to the user of the api.

Can't it be tackled using specification extensions?
Like in the open api spec.

Describe the solution you'd like
OpenApi example:
{ "openapi": "3.0.0", "info": { "title": "Swagger specification", "version": "1.0.0" }, "components": { "schemas": { "EnumDemo": { "type": "integer", "description": "", "x-enumNames": [ "Value0", "Value1", "Value2", "Value3", "Value4" ], "enum": [ 0, 1, 2, 3, 4 ] } } } }

Additional context
Otherwise enums are pretty useless :/

I have an object property in a payload which is defined as follows:

                    "crs": {
                      "description": "Coordinate reference system specified as [EPSG](http://www.epsg.org) code or [PROJ](https://proj4.org) definition. Defaults to `4326` (EPSG code 4326) unless the client explicitly requests a different coordinate reference system.",
                      "oneOf": [
                          {
                              "title": "EPSG Code",
                              "type": "integer",
                              "format": "epsg-code",
                              "example": 7099
                          },
                          {
                              "title": "PROJ definition",
                              "type": "string",
                              "format": "proj-definition",
                              "example": "+proj=moll +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs"
                          }
                      ],
                      "default": 4326
                    },

Running the generator on it returns:

Invalid JSON obtained from the content of the AsyncAPI specification file
[ { code: 'OBJECT_ADDITIONAL_PROPERTIES',
    params: [ 'oneOf' ],
    message: 'Additional properties not allowed: oneOf',
    path: '#/topics/data/publish/payload/properties/payload/properties/spatial_extent/properties/crs',
    schemaId: 'http://asyncapi.hitchhq.com/v1/schema.json#',
    description: 'A deterministic version of a JSON Schema object.',
    [Symbol(z-schema/schema)]: 
     { additionalProperties: false,
       properties: [Object],
       patternProperties: [Object],
       description: 'A deterministic version of a JSON Schema object.',
       type: 'object',
       '__$validated': true },
    [Symbol(z-schema/json)]: 
     { asyncapi: '1.0.0',
       info: [Object],
       externalDocs: [Object],
       baseTopic: 'openeo',
       topics: [Object],
       components: [Object] } } ]

I don't see this backed by the spec. It seems as if it is allowed to have things such as a default value and a description on the same level as oneOf etc. So it would be great to get a fix for this.

In many enterprise environments there are restrictions on what agents can be written in… sometimes Node.js isn't allowed.

On the documentation page for AsyncAPI https://github.com/asyncapi/node-codegen is listed as deprecated in favor of asyncapi-generator.

However, there are no nodejs templates in the generator. Is it possible to port them?
Since node-codegen is no longer functional ( current version breaks during the tutorial).

Right now the CLI doesn't support passing parameters specific to a template.

Having a way to pass additional information to a template can open the door to a lot of flexibility.
For example, for the java generator, we could use the following commands to generate the same code but with different build tools like maven or gradle:
ag asyncapi.yaml java-spring maven
ag asyncapi.yaml java-spring gradle

I'm not sure if the commander library supports this type of workflow. I'll try to find that out.

This is a follow-up for asyncapi/spec#98 . I attempted the client side code generator and it seemed fairly intuitive for the most part.

• I tried to do write the generator for this schema: https://github.com/asyncapi/asyncapi/blob/master/test/docs/slack-rtm.yml
• I used this for reference when unsure about parts of the schema: https://github.com/asyncapi/asyncapi/blob/master/README.md
• And here is what I can currently generate (not finished): https://github.com/bali182/asyncapi-ws-to-ts/blob/master/slackApi.ts

I have a few points of feedback (mind that this is for the websocket version, but some of this might be relevant for other protocols too).

1. It would be beneficial to add the concept of operationId in OpenAPI 3.0 to Message Object. In the Slack example both the send and receive list in the events object were refs, and the name of the refs could be used as method names. However these fields allow inline Message Objects, and in this case the method name cannot be inferred.
2. Make it possible to discriminate payloads (Message Object payloads). In the example I could do this by using the enum constants in payloads with a single possible value (type and subtype). But in case this is not available, it can be very costly to validate the full schema just to determine what type of message it is.
3. This might be just a problem with the slack schema, but according to the json schema spec, any part of the schema that doesn't have the "required": true field set, is not required, and can be ommited. In the slack schema all fields are optional.

Docker tag should match application version.
Currently all tags are '0.1.0' and 'latest'.

Use case:
When version is broken, there is no way to install previous working docker image with stable version.

It's the slashes. I would have submitted a PR, but I wasn't sure the right way to do it in node. The following does work, though.

    if (!file_path.startsWith('.partials') && !file_path.startsWith('.helpers')) {

Environment:

– macOS Mojave 10.14.6
– docker 19.03.1

Steps to reproduce:

1. Execute command from the README:

docker run --rm -it -v $PWD:/app -w /app asyncapi/generator -V

Actual result:

docker run --rm -it -v $PWD:/app -w /app asyncapi/generator -V
Unable to find image 'asyncapi/generator:latest' locally
docker: Error response from daemon: pull access denied for asyncapi/generator, repository does not exist or may require 'docker login': denied: requested access to the resource is denied.
See 'docker run --help'.

Expected result:

Generator version is written on the terminal.

What?

When copying a file from the template to the destination directory, it should respect the file's chmod configuration. At least the executable part. For instance, when generating a Java project, we want gradlew to be executable.

Why?

We should offer a ready-to-use result from the templates.

When an object is referenced by an array, the property descriptions of the referenced object are not generated and printed in HTML.

See the following demo specification and use https://playground.asyncapi.io/

asyncapi: '2.0.0-rc1'
id: 'urn:demo'
info:
title: Demo
version: '1.0'

channels:

demo/channel:
publish:
message:
$ref: '#/components/messages/demoMessage'

components:

messages:

demoMessage:
  name: demoMessage
  payload:
    $ref: '#/components/schemas/demoHeader'

schemas:

demoHeader:
  type: object
  properties:
    id:
      type: string
      description: The id
    demoItems:
      type: array
      description: The items of the header
      items:
        $ref: '#/components/schemas/demoItem'

demoItem:
  type: object
  properties:
    id:
      type: string
      description: The id of the demoItem
    name:
      type: string
      description: The name of the demoItem
    type:
      type: string
      description: The type of the demoItem

I can't install this software on Windows though it doesn't state this in the README. It only says it requires node, nothing about a specific OS.

NPM response:

c:\Dev\openeo-api>npm install -g ag
npm ERR! code EBADPLATFORM
npm ERR! notsup Unsupported platform for [email protected]: wanted {"os":"darwin,linux,!win32","arch":"x64"} (current: {"os":"win32","arch":"x64"})
npm ERR! notsup Valid OS:    darwin,linux,!win32
npm ERR! notsup Valid Arch:  x64
npm ERR! notsup Actual OS:   win32
npm ERR! notsup Actual Arch: x64

Would be great to get Windows support back!

The generator will break on binary files like jar files. As part of the java-spring generator a jar file needs to be copied(see picture)

I see the method renderFile in generator.js is trying to compile all files as Handlebars templates:
try { const template = Handlebars.compile(content); const parsed_content = template(data); resolve(parsed_content); } catch (e) { reject(e); }

Suggested solution: declare in a config file under the template directory to declare ignore files to be compiled as Handlebars templates.

Os : macOs 10.14.15
node : v12.3.1

Installation doesn't work with version 0.7.0. the last version to work is 0.6.7

make: *** [Release/obj.target/binding/src/binding.o] Error 1
gyp ERR! build error
gyp ERR! stack Error: make failed with exit code: 2
gyp ERR! stack at ChildProcess.onExit (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:262:23)
gyp ERR! stack at ChildProcess.emit (events.js:200:13)
gyp ERR! stack at Process.ChildProcess._handle.onexit (internal/child_process.js:272:12)
gyp ERR! System Darwin 18.6.0
gyp ERR! command "/usr/local/Cellar/node/12.3.1/bin/node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/asyncapi-generator/node_modules/ref
gyp ERR! node -v v12.3.1
gyp ERR! node-gyp -v v3.8.0
gyp ERR! not ok
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] install: node-gyp rebuild
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] install script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:

Third times a charm...

I've already figured out the fix for this, but don't have time in the moment to submit a PR - so I'll at least capture my findings here and work on the PR later (or if someone else wants to pick this up).

When a Channel has both a Pub and Sub Operation, and your browser width is greater than (approximately) 1248 pixels, the Pub and Sub Operations are displayed in the same row and share the remaining row width (with some overflow depending on how small your resolution is). This can be seen here (intentionally showing the x-overflow issue as well):

This can be fixed by moving each Operation's HTML into a separate <div class="responsive-container">, whereas currently both Pub and Sub Operations are nested under the same responsive-container div.

Picture for clarity. Just need to insert </div><div class="responsive-container"> above the highlighted row to fix the issue.

After applying this fix (in dev console of browser):

They do show up in the Schemas section however:

topics:
  example:
    subscribe:
      description: Example topic
      payload:
        $ref: '#/components/schemas/example'

components:
  schemas:
    example:
      type: array
      items:
        type: number
      example: [35.4, 38.6, 46.7, 66.5]

Assuming an HTML generated document.

The example within the "Topics" section just shows an empty code block. However in the schemas section section the example shows correctly.

This works the same using the online editor, as well as with the ag cli.

As the title states. Which versions of Asyncapi does this work for?

Currently the "tags" system only add tags under each operation.
There's no further functionality as far as I can see.

Swagger also has tags, and uses them for structure. See the pet store example: https://petstore.swagger.io/#/ .. Pet, store, user, etc.. are tags and they provide structure to the document by grouping.

I'm currently documenting a rather big MQTT API and it's very hard to navigate through it at the moment.
The left sidebar is just one big (randomised order) list of summaries of operations. Ideally there would be a hierarchical (collapsible) structure

tag
  - operations
tag2
  - operations

The content of the page could also add header titles with tags (see the above pet store example) and even better: have a table of contents / nav with all tags displayed above (anchor links)

The must match XXX badge from the schema is being capitalized (text-transform: capitalize)
Example:

schemas:
    Foo:
      type: object
      properties:
        bar:
          type: string
          pattern: "^hello$"

Is being shown as Must Match ^Hello$

In somehow it's related to https://github.com/asyncapi/generator/pull/62/files

helloworld.yaml:

asyncapi: '2.0.0-rc1'
id: 'urn:hello-world-app'
info:
  title: Hello world application
  version: '0.1.0'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.htm
channels:
  hello:
    subscribe:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

With v0.9.0:

$ npx [email protected] --output dist/ helloworld.yaml html
Done! ✨
Check out your shiny new generated files at /Users/laat/git/example/dist.

With v0.10.0:

$ npx [email protected] --output dist/ helloworld.yaml html
Something went wrong:
TypeError: Cannot read property 'index.html' of undefined
    at Generator.generateFile (/Users/laat/.npm/_npx/34040/lib/node_modules/asyncapi-generator/lib/generator.js:381:47)
    at Walker.walker.on (/Users/laat/.npm/_npx/34040/lib/node_modules/asyncapi-generator/lib/generator.js:288:26)
    at Walker.emit (events.js:198:13)
    at Object.emitSingleEvents [as emitNodeType] (/Users/laat/.npm/_npx/34040/lib/node_modules/asyncapi-generator/node_modules/walk/lib/node-type-emitter.js:58:13)
    at Walker._wLstatHandler (/Users/laat/.npm/_npx/34040/lib/node_modules/asyncapi-generator/node_modules/walk/lib/walk.js:88:19)
    at /Users/laat/.npm/_npx/34040/lib/node_modules/asyncapi-generator/node_modules/walk/lib/walk.js:106:12
    at FSReqWrap.oncomplete (fs.js:154:5)

initial investigation suggests that .tp-config.json is missing in the template folder in this repository

It would be awesome to have a code generator for Go. Anyone around who wants to participate?

This is less of an issue if your parameters are all contained in the path of the channel, but unfortunately (as far as I know) AWS API Gateway does not allow you to specify path parameters in their WebSocket API definitions. Therefore I have to use querystring parameters to pass parameters upon establishing a websocket connection to a particular channel.

Using this example model if you generate the HTML from it you can only see one example message leaving the others hidden to the reader of the documentation.

# Standard header elements

channels:
  /socket/{subscription_id}:
    parameters:
      - name: subscription_id
        schema:
          type: string
    publish:
      message:
        oneOf:
          - summary: Register subscription
            contentType: application/json
            payload:
              type: object
              properties:
                name:
                  type: string
                  enum: [register]
          - summary: Send still alive message to the Hive.
            contentType: application/json
            payload:
              type: object
              properties:
                name:
                  type: string
                  enum: [still_alive]
                payload:
                  type: object
                  properties:
                    id:
                      type: string
                      description: This is the id from the keep_alive message.

Three useful constraints of strings are not rendered in the HTML template.

These are:

• minLength
• maxLength
• pattern

They are - along with other constraints - described at https://www.asyncapi.com/docs/specifications/1.2.0/#schemaObject.

As defined in the specification, any Schema Object MAY have a "nullable" property, but I can't make it working in the editor, nor find it in the spec implementation (https://github.com/asyncapi/asyncapi/blob/master/schema/asyncapi.json)

Should it be removed from the doc ?

When the specification contains a contact entry in the info section, it is not displayed in the preview panel.

I am playing around with references to local files and can't get it to work with the generator and referencing a yaml file.

basic_example_refs.yml:

asyncapi: '2.0.0-rc1'
id: 'urn:array.example.com'

info:
  title: Very simple example
  version: '1.0.0'

channels:
  myChannel:
    publish:
      message:
        description: Simple example
        payload:
          $ref: './myObject.yml#/myObject'

components:
  schemas:
    myObject:
      type: object
      properties:
        key1:
          title: A key
          type: string
          default: "foo"
          enum:
            - foo
            - bar
          description: Just an example enum

myObject.yml:

myObject:
  type: object
  properties:
    key1:
      title: A key
      type: string
      default: "foo"
      enum:
        - foo
        - bar
      description: Just an example enum

Both are in the same directory. I am trying this on Windows. When doing this with the myObject.yml file, I get the following error:

C:\[...]\asyncapi-test\asyncapi-refs>ag basic_example_refs.yml html
2019/06/12 17:15:38 invalid character 'm' looking for beginning of value

After reading reusing messages, I thought that yaml files can be used. The 2.0.0-rc1 spec and this issue indicate that it might not be possible, though. However, when I am trying the same thing with a local json file, it works:

Changed basic_example_refs.yml:

        payload:
          $ref: './myObject.json#/myObject'

myObject.json:

{
  "myObject": {
    "type": "object",
    "properties": {
      "key1": {
        "title": "A key",
        "type": "string",
        "default": "foo",
        "enum": [
          "foo",
          "bar"
        ],
        "description": "Just an example enum"
      }
    }
  }
}

C:\[...]\asyncapi-test\asyncapi-refs>ag basic_example_refs.yml html
Done! ✨
Check out your shiny new generated files at C:\[...]\asyncapi-test\asyncapi-refs.

Is this an issue of the generator or am I doing something wrong here? Thanks in advance,
Marco

here is a proposal to add a new property to the .tp-config.json file

{
  "schemeFiles" : {
    "amqp": [
      "src/main/java/com/asyncapi/service/AmqpConfig.java",
      "src/main/java/com/asyncapi/service/AmqpMessageHandlerService.java",
      "src/main/java/com/asyncapi/service/AmqpPublisherService.java"
    ],
    "mqtt": [
      "src/main/java/com/asyncapi/service/mqtt/"     
    ]
  }  
}