search

asyncapi-archived-repos / docgen

AsyncAPI documentation generator. DEPRECATED in favour of
https://github.com/asyncapi/generator
Apache License 2.0
21 stars 11 forks source link

Slash notation for topics #17

Closed riccardo1991 closed 6 years ago

riccardo1991 commented 6 years ago

Is there any way to implement the slash notation for topics with a defined base topic?

I have: baseTopic: v1

and a topic: /sb/{did}/telemetry/{id}

then I see in the editor a dot between the base topic and the topic itself: v1./sb/{did}/telemetry/{id}

fmvilas commented 6 years ago

Let me clarify something here:

/sb/{did}/telemetry/{id}: I know that MQTT uses slashes to separate topic parts but in the AsyncAPI notation we use dots. That's why you correctly get v1./sb/{did}/telemetry/{id}.

You have three options here:

  1. Use dot notation: sb.{did}.telemetry.{id} in your AsyncAPI file. This will make sense as it's what you actually want to describe and the code generators already perform a dot->slash substitution for protocols like MQTT.
  2. Tweak docgen to allow substitution of the separator, i.e. dot->slash. (I can help on that)
  3. Do both.

Just out of curiosity, can I ask you what programming language are you using?

fmvilas commented 6 years ago

I just did the change mentioned in point 2. To specify a different topic separator just add x-topic-separator: "/" to the root level of your AsyncAPI document.

Example:

asyncapi: "1.0.0"
info:
  title: My API
  version: "2.1.0"
x-topic-separator: "/"

But remember, the correct notation in your AsyncAPI document should be sb.{did}.telemetry.{id}.

It's also available in the editor now: asyncapi.editor.org.

fmvilas commented 6 years ago

@riccardo1991 I think this might be of your interest: https://github.com/asyncapi/docgen/pull/19