Create a dummy-like asyncapi document for testing templates functionality

[derberg]

Reason:
At the moment, we manually test templates on a streetlight.yml example that we also modify from time to time. At some point of time, it will become a Frankenstein, and that is not the purpose of streetlight example. We should have a very dummy example that is easy to extend with all possible use cases. Later we could share it as an official test document that other templates should be tested against

Description:

• Take current streetlight and replace with dummy yaml
• Make sure it works with current templates
• remove streetlights example
• updated contribution docs with info that every enhancement in templates should extend dummy example if needed

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

instead of creating a dummy file, maybe we should just use https://github.com/asyncapi/tck/ as dependency to projects that need testing and use spec docs from this package?

[jonaslagoni]

Yea agree, we could use that instead :)

[derberg]

@jstoiko @postatum @fmvilas
Hey guys, what do you think about the idea of releasing tck to npm so I can add it to my devDependencies and use specs that are stored there to test functionalities of templates

[postatum]

Hi @derberg. Meanwhile you can use the tck in your devDependencies like

"tck": "github:asyncapi/tck"

[derberg]

@postatum yeah but you know that without proper release to npm or at least github it is super risky assuming that the directory structure of the files will never change and that maintainers know what is the purpose of the repo

[derberg]

or maybe because we are also supporting fetching of spec since next week, maybe instead of publishing to npm better to have it as a part of the deployment to GitHub Pages? 🤔

[derberg]

After some research I don't think tck is what we need here. Sorry @postatum and @jstoiko for pinging you without checking the idea first.

tck purpose is to check parsers coverage and it is split into multiple pieces, small parts sometimes invalid to make sure parser throws errors. This is not very usable for developing generator templates.

I took streetlight, and modified it a bit to make is a dummy example and covered most of the features (they already show that html-temple misses some coverage).

asyncapi: '2.0.0'

externalDocs:
  description: Find more info here
  url: https://www.asyncapi.com

info:
  title: Dummy example with all spec features included
  version: '0.0.1'
  description: |
    This is an example of AsyncAPI specification file that is suppose to include all possible features of the AsyncAPI specification.

    It's goal is to support development of documentation and code generation with the [AsyncAPI Generator](https://github.com/asyncapi/generator/) and [Template projects](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate)
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: API Support
    url: http://www.asyncapi.com/support
    email: [email protected]
  x-twitter: '@AsyncAPISpec'

tags:
  - name: root-tag1
    externalDocs: 
      description: External docs description 1
      url: https://www.asyncapi.com/
  - name: root-tag2
    description: Description 2
    externalDocs:
      url: "https://www.asyncapi.com/"
  - name: root-tag3
  - name: root-tag4
    description: Description 4
  - name: root-tag5
    externalDocs:  
      url: "https://www.asyncapi.com/"

servers:
  dummy-mqtt:
    url: mqtt://localhost
    protocol: mqtt
    description: dummy MQTT broker
    bindings:
        mqtt:
          clientId: guest
          cleanSession: true
  dummy-amqp:
    url: amqp://localhost:{port}
    protocol: amqp
    description: dummy AMQP broker
    protocolVersion: "0.9.1"
    variables:
      port:
        enum:
          - '15672'
          - '5672'
    security:
      - user-password: []
  dommy-kafka:
    url: http://localhost:{port}
    protocol: kafka
    description: dummy Kafka broker
    variables:
      port:
        default: '9092'

defaultContentType: application/json

channels:
  dummy/channel/with/{dummy}/parameter/create:
    description: Dummy channel description.
    parameters:
      dummy:
        $ref: '#/components/parameters/dummy'
    publish:
      summary: Inform whenever something dummy is created.
      description: |
        Longer description.

        Still dummy though.
      operationId: receiveNewDummyInfo
      tags:
        - name: oparation-tag1
          externalDocs: 
            description: External docs description 1
            url: https://www.asyncapi.com/
        - name: oparation-tag2
          description: Description 2
          externalDocs:
            url: "https://www.asyncapi.com/"
        - name: oparation-tag3
        - name: oparation-tag4
          description: Description 4
        - name: oparation-tag5
          externalDocs:  
            url: "https://www.asyncapi.com/"
      traits:
        - $ref: '#/components/operationTraits/kafka'
      message:
        $ref: '#/components/messages/dummyCreated'

  dummy/channel/without/parameter:
    bindings:
      amqp:
        is: routingKey
    subscribe:
      operationId: receiveSystemInfo
      message:
        $ref: '#/components/messages/dummyInfo'

components:
  messages:
    dummyCreated:
      name: dummyCreated
      title: Dummy created message
      summary: This is just a dummy create message
      tags:
        - name: message-tag1
          externalDocs: 
            description: External docs description 1
            url: https://www.asyncapi.com/
        - name: message-tag2
          description: Description 2
          externalDocs:
            url: "https://www.asyncapi.com/"
        - name: message-tag3
        - name: message-tag4
          description: Description 4
        - name: message-tag5
          externalDocs:  
            url: "https://www.asyncapi.com/"
      headers:
        type: object
        properties:
          my-custom-app-header:
            type: string
      payload:
        $ref: "#/components/schemas/dummyCreated"
    dummyInfo:
      name: dummyInfo
      title: Dummy system info
      summary: This is just a dummy info message
      description: |
        More description for a dummy message.

        It is a dummy system info message.
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
      payload:
        $ref: "#/components/schemas/dummyInfo"
      examples:
        - one:
            prop1: option1
            sentAt: 2020-01-26T13:00:00Z
        - two:
            prop1: option1
            sentAt: 2020-01-31T13:24:53Z

  schemas:
    dummyCreated:
      type: object
      properties:
        prop1:
          type: integer
          minimum: 0
          description: Dummy prop1
        prop2:
          type: string
          description: Dummy prop2
        sentAt:
          $ref: "#/components/schemas/sentAt"
      additionalProperties: false
    dummyInfo:
      type: object
      properties:
        prop1:
          type: string
          enum:
            - option1
            - option2
          description: Dummy prop1
        sentAt:
          $ref: "#/components/schemas/sentAt"
    sentAt:
      type: string
      format: date-time
      description: Date and time when the message was sent.

  securitySchemes:
    user-password:
      type: userPassword
    apiKey:
      type: apiKey
      in: user
      description: Provide your API key as the user and leave the password empty.
    supportedOauthFlows:
      type: oauth2
      description: Flows to support OAuth 2.0
      flows:
        implicit:
          authorizationUrl: 'https://authserver.example/auth'
          scopes:
            'streetlights:on': Ability to switch lights on
            'streetlights:off': Ability to switch lights off
            'streetlights:dim': Ability to dim the lights
        password:
          tokenUrl: 'https://authserver.example/token'
          scopes:
            'streetlights:on': Ability to switch lights on
            'streetlights:off': Ability to switch lights off
            'streetlights:dim': Ability to dim the lights
        clientCredentials:
          tokenUrl: 'https://authserver.example/token'
          scopes:
            'streetlights:on': Ability to switch lights on
            'streetlights:off': Ability to switch lights off
            'streetlights:dim': Ability to dim the lights
        authorizationCode:
          authorizationUrl: 'https://authserver.example/auth'
          tokenUrl: 'https://authserver.example/token'
          refreshUrl: 'https://authserver.example/refresh'
          scopes:
            'streetlights:on': Ability to switch lights on
            'streetlights:off': Ability to switch lights off
            'streetlights:dim': Ability to dim the lights
    openIdConnectWellKnown:
      type: openIdConnect
      openIdConnectUrl: 'https://authserver.example/.well-known'

  parameters:
    dummy:
      description: The ID of the new dummy message.
      schema:
        type: string

  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          my-app-header:
            type: integer
            minimum: 0
            maximum: 100

  operationTraits:
    kafka:
      bindings:
        kafka:
          clientId: my-app-id

We would keep it in the generator repository, and template devs would be informed it is there, and if they need "more", they should extend the example with "more".

During development, they could use new generator feature, and fetch the dummy spec from generator repo

Yes, I know it is not possible that some user might have a spec with 3 servers supporting 3 different protocols, but it is just a dummy document to make development easier and that is it

I checked and what I created works well, nodejs-template works like a charm

@jonaslagoni @fmvilas what do you think folks?

[jonaslagoni]

Looks great! Should be useful 👍 When it's done I'm gonna add NATS support to the document and test it out with the NATS template 😄

[fmvilas]

Sounds good. This is something we'll improve over time for sure.

[asyncapi-bot]

🎉 This issue has been resolved in version 0.52.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀