Cannot generate AsyncAPI 2.0.0 documentation

[cvalb]

Hello!

I'm testing various packages for Async Api documentation and this seems to be the most suited for my purposes, because it works with both OpenApi and AsyncApi patterns.

I kept getting this error trying to generate a document from a AsyncApi 2.0.0 yaml file, while the same function is working fine with my OpenApi 3.0.3 yaml file:

/home/xpto/event-documentation/node_modules/swagger-jsdoc/src/specification.js:173
      swaggerObject.paths[property],
                         ^
TypeError: Cannot read property 'asyncapi' of undefined
    at organize (/home/xpto/event-documentation/node_modules/swagger-jsdoc/src/specification.js:173:26)
    at build (/home/xpto/event-documentation/node_modules/swagger-jsdoc/src/specification.js:316:7)
    at module.exports (/home/xpto/event-documentation/node_modules/swagger-jsdoc/src/lib.js:32:10)
    at Object.documentation (file:///home/xpto/event-documentation/scopes/documentation/swaggerJsdoc/middlewares.js:49:10)
    at file:///home/xpto/event-documentation/scopes/documentation/swaggerJsdoc/index.js:13:43
    at ModuleJob.run (internal/modules/esm/module_job.js:183:25)
    at Loader.import (internal/modules/esm/loader.js:178:24)
    at Object.loadESM (internal/process/esm_loader.js:68:5)

Here is the way I'm using the package:

import swaggerJsdoc from 'swagger-jsdoc'
import path from 'path'

const swaggerPath = path.resolve('docs', 'swagger', 'swagger.yaml')
const asyncApiPath = path.resolve('docs', 'asyncApi','asyncApi.yaml')

// pattern = { name, version }
const documentation = (pattern, sourcePaths, title = 'API Documentation', version = '1.0.0') => {
  let options = {
    definition: {
      info: {
        title: title,
        version,
      },
    },
    apis: sourcePaths, 
  }

  options.definition[pattern.name] = pattern.version

  return swaggerJsdoc(options)
}

documentation({ name: 'asyncapi', version: '2.0.0' }, [asyncApiPath], 'Async API')
documentation({ name: 'openapi', version: '3.0.3' }, [swaggerPath], 'REST API')

The yaml file is working fine on editors like studio.asyncapi.com and I'm able to serve it with @asyncapi/generator:

asyncapi: 2.0.0
info:
  title: AsyncAPI Sample App
  description: This is a sample server.
  termsOfService: http://asyncapi.org/terms/
  contact:
    name: API Support
    url: http://www.asyncapi.org/support
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.1
channels:
  user/signedup:
    description: This channel is used to exchange messages about users signing up
    subscribe:
      summary: A user signed up.
      message:
        description: A longer description of the message
        payload:
          type: object
          properties:
            user:
              $ref: "#/components/schemas/user"
    bindings:
      amqp:
        is: queue
        queue:
          exclusive: true
components:
  schemas:
    user:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        age:
          type: integer
          format: int32
          minimum: 0

So I tried to generating from a .js file, which is most likely the way I'm going to use it, but I get a blank Async API documentation.

This is the .js file I'm trying to generate from:

/**
 * @asyncapi
 * user/signedup:
 *  description: This channel is used to exchange messages about users signing up
 *   subscribe:
 *    summary: A user signed up.
 *     message:
 *      description: A longer description of the message
 *      payload:
 *       type: object
 *       properties:
 *        user:
 *         type: object
 *         required:
 *          - name
 *         properties:
 *          name:
 *           type: string
 *          age:
 *           type: integer
 *           format: int32
 *           minimum: 0
 */

The documentation generated:

{
    "info": {
        "title":"AsyncApi",
        "version":"1.0.0"
    },
    "asyncapi":"2.0.0",
    "components":{},
    "channels":{},
    "tags":[]
}

Thanks.

[prisis]

Hey :)

/**
 * @asyncapi
 * channels:
 *   /user/signedup:
 *    description: This channel is used to exchange messages about users signing up
 *    subscribe:
 *      summary: A user signed up.
 *      message:
 *        description: A longer description of the message
 *        payload:
 *         type: object
 *         properties:
 *          user:
 *           type: object
 *           required:
 *            - name
 *           properties:
 *            name:
 *             type: string
 *            age:
 *             type: integer
 *             format: int32
 *             minimum: 0
 */

you had 2 small mistakes in your example

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[daniloab]

can you check the @prisis answer? @cvalb