asyncapi-archived-repos / docgen Goto Github PK

In some cases documentation is stored within the repo. html is usually not allowed to be rendered when browsing the repo, while markdown is.

Please consider adding support for markdown rendering, https://github.com/adobe/jsonschema2md here is example of renderer for JSON Schema.

AsyncAPI supports a property called externalDocs which references external documentation for a particular item. It would be nice to render these links in the docs.

It would be nice if the docgen can automatically generate JSON/XML sample for the payload. Similar to what widdershins + slate does.

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}

I used this module to generate HTML documents from Node, but it throws the exception:

Error: Invalid .validate call - schema must be an string or object but undefined was passed!

But I can preview my YAML content on http://editor.asyncapi.org/

Please help. Thanks a lot

Look like https://github.com/asyncapi/generator is the same project with more capabilities ?

Even though I discourage to use different messages for the publish operation and the subscribe operation, it's something people are doing so we have to support it. Example:

https://ubidots.com/docs/api/mqtt.html#subscribe-to-a-variable

In this image, we can see how id is part of the message but it's only there when subscribing.

We're currently documenting message payloads as if they're always JSON objects, but the reality is that it can be something else, for instance, a number. Here's an example:

https://ubidots.com/docs/api/mqtt.html#subscribe-to-a-variable

It says:

/v1.6/devices/{LABEL_DEVICE}/{LABEL_VARIABLE}/lv: This will return the last value of the variable as a single float value. This makes it easier to parse in microcontrollers.

That's especially important for IoT devices.

Opening the online editor generates HTML output with topics assembled fro m different parts, where some of the parts seem to be undefined:

hitchundefinedaccountsundefined1undefined0undefinedactionundefineduserundefinedsignup

The same can be reproduced running adg locally.

Thank you for great tool! But could you add some examples, simple howto-s and demos for quick starting. As for me your tool seems like what I need for my async project, but I stuck with different options and how all of them will be looking in result of generaion. Thanks in advance!

Check asyncapi/spec#49. Thanks @riccardo1991 for reporting.

I'm getting the same error like in same issue, but with latest version "asyncapi-docgen": "^1.10.3". Please help.

When executing adg directly from the shell, the program always returns a zero exit code, even when the documentation generation process fails. Common convention is to return a non-zero exit code when the operation was not successful.

This prevents simple utilization in continuous integration scripts, instead requiring an implementation to call the program from another node script or carefully monitor stdout/stderr to check for success.

To reproduce:

$ npm install -g asyncapi-docgen
$ touch BadFile.yaml
$ adg BadFile.yaml
$ echo $?

This should return anything other than zero on a failed case.

Tested versions: 1.7.1, 1.7.2
Tested OS: MacOS 10.12, Debian 9

Because (I think) of the way nested properties are output, the content (items) of arrays are not expanded. Unsure if this is by design or not?

Add API license information in the introduction block.

the generated docs are already awesome but I would like to have a try it out button!

is it possible add a hook / extensionpoint for that?

Im thinking if scheme is mqtt and the server uses http(s) add mqtt.js to the webpage. then add a connect button (with login form). and depending on the action publish example data or subscribe and show the incoming messages

Great tool, very useful. It would be great to make it easily possible to use template. For example, I'd like to have all my generated documentation to have a common header so that users can navigate between the different pages, but I don't see such an option here whereas ReDoc and other tools allow it. I don't really want to fork the whole repository, but simply use it with the cli and npm tools.

It seems that there is an issue with rendering of required properties of SchemaObject. E.g. for a following API schema first_field of testSchema won't be rendered as a required.

asyncapi: "1.1.0"
info:
  title: Required fields issue demo
  version: "0.0.1"

topics:
  test:
    publish:
      $ref: "#/components/messages/testMessage"
      
components:
  messages:
    testMessage:
      summary: Testing
      payload:
        $ref: "#/components/schemas/testSchema"

  schemas:
    testSchema:
      type: object
      required:
        - first_field
      properties:
        first_field:
          type: string
        second_field:
          type: string

From what I see inschema-prop template, there is a check of required array existance inside the prop object while it needs to check that parent schema object has propName in required array.

I have WIP fix for this issue in a forked repo, so please let me know if you want me to submit a PR. Looking forward for you feedback.

Right now it only supports APIs with topics section. It would be nice to add support for events and stream sections too.

Merging parts of different objects is fun. OpenAPI understands it but unfortunately cant render it properly in editor and offline documentation.

Simplest example:

asyncapi: 1.0.0
info:
  title: Example API
  version: "1.0"
topics:
  example.topic:
    publish:
      payload:
        allOf:
          - type: object
            properties:
              foo:
                type: string
          - type: object
            properties:
              bar:
                type: string

Results in empty payload table:

AsyncAPI does not mention about its limitations and OpenAPI plays with XOf nicely.

There is no LICENSE file, and neither README.md or package.json mention how the code is licensed. May also be worth noting that a version of Node.js with async/await support (v8.x.x+ I think) is required.

topics:
  event.teltonika.{serial}.mobile.bytes_received:
    parameters:
      - name: "serial"
        description: "Serial number of the router. Serial number can be taken from the device or via the command: `uci get hwinfo.hwinfo.serial`."
        schema:
          type: "string"
          title: "Serial number"
          description: "Serial number, usually 8 digests long."
          example: "01234567"

The example is not shown/empty :(

Using the online editor with the option I get the following result:

It might be a problem of the online editor, I did not try this tool from git sources.

Nesting at least 2 level of "allOf" does not seem to work:

asyncapi: "1.2.0"
info:
  title: Title
  version: "1.0.0"
  description: Description

servers:
- url: rabbitmq:5676/
  scheme: amqp

topics:
  my_topic:
    publish:
      $ref: "#/components/messages/my_topic"

components:
  messages:
    my_topic:
      summary: Topic1 message
      description: Bla bla
      payload:
        $ref: "#/components/schemas/BazWithQux"

  schemas:
    Foo:
      type: object
      required:
      - foo
      properties:
        foo:
          type: string

    Bar:
      type: object
      required:
      - bar
      properties:
        bar:
          type: string

    Baz:
      allOf:
      - $ref: "#/components/schemas/Foo"
      - $ref: "#/components/schemas/Bar"

    BazWithQux:
      allOf:
      - $ref: "#/components/schemas/Baz"
      - type: object
        required:
        - qux
        properties:
          qux:
            type: string

The "qux" property does not show in the "BazWithQux" object

Some APIs allow you to send payloads in different ways/formats. Example:

https://ubidots.com/docs/api/mqtt.html#publish-values-to-a-device