Expanded tags support: allow adding tags to more entities, support refs

[gabormagyar]

Tags are great! I see two low hanging improvements that could be made to them:

Refs

Tags could be added under components, and could be referenced in other places so that tags (potentially with documentation and info links) don't have to be duplicated across usages

More entities

I tried to add tags to schemas, but the parser told me that that was invalid. I see no reason to disallow this. Should probably consider other places where tags may be applicable.

Relevant slack thread with @magicmatatjahu: https://asyncapi.slack.com/archives/CQVJXFNQL/p1649332581535119

[github-actions[bot]]

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.

[derberg]

@gabormagyar can you specify where exactly you would like to see Tag object enabled, and share example? Because we do releases regularly we always try to add things only that have use case rather that assuming use case 😄 I guess you know what I mean.

I also understand you'd like to have it also in components so it can be refed from other parts of the document

[gabormagyar]

Right now I have most of my channels looking like this:

subscribe:
  message:
    payload:
      $ref: @schemas/payload.yml
publish:
  description: Description
  message:
    payload:
      $ref: @schemas/payload.yml
tags:
  - {{ mixin('@tags/producer-driven.yml.njk') }}

mixin is provided by boats, and I do a separate postprocess step on the final yaml to take the top level tags and copy them into the publish and subscribe operations. My output looks like this:

subscribe:
  message:
    payload:
      $ref: ../../../components/schemas/payload.yml
  tags:
    - name: tag-name
      description: >-
        Tag description
      externalDocs:
        description: More info
        url: >-
          https://github.com/.../README.md
publish:
  description: Description
  message:
    payload:
      $ref: ../../../components/schemas/payload.yml
  tags:
    - name: tag-name
      description: >-
        Tag description
      externalDocs:
        description: More info
        url: >-
          https://github.com/.../README.md

[smoya]

FYI, https://github.com/asyncapi/spec/pull/809 adds support for Tags at Server Object level.

[magicmatatjahu]

Adding tags on Schema Object level https://github.com/asyncapi/spec/pull/796

[magicmatatjahu]

Reusable Tag and External Documentation objects https://github.com/asyncapi/spec/pull/792

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: