scribano

command module
Version: v0.0.0-...-cb39d06 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 2, 2019 License: MIT Imports: 7 Imported by: 0

README

Scribano

Codacy Badge CircleCI

Builds an asyncapi documentation for your microservices communicating through rabbitmq.

It listens to all published amqp messages and keeps an updated asyncapi compliant documentation served at /asyncapi.

Sample configuration can be found here.

How does it work?

Scribano will subscribe to a set of configured RabbitMQ exchanges, and will start consuming events from there.

When a message is consumed, scribano will infer a structure for the content. For example, after consuming a message on the some.key routing key with the following payload:

{
  "name": "infer type",
  "age": 27,
  "grade": 9.5,
  "canDrive": false,
  "birthDate": "1991-08-29",
  "lastLogin": "2015-06-10T13:23:30-08:00",
  "address": null,
  "emptyHash": {},
  "fines": [],
  "emptyHashes": [{}],
  "matrix": [
    [1, 2, 3],
    [3, 2, 1]
  ],
  "friends": [
    { "name": "pepe" },
    { "name": "gotera" }
  ],
  "car": {
    "brand": "mercedes"
  }
}

The following spec will be served on /asyncapi

{
  "asyncapi": "1.0.0",
  "info": {
    "title": "",
    "version": ""
  },
  "topics": {
    "some.key": {
      "publish": {
        "$ref": "#/components/messages/SomeKey"
      },
      "x-exchange": "/my-exchange"
    }
  },
  "components": {
    "messages": {
      "SomeKey": {
        "payload": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "age": {
              "type": "integer"
            },
            "grade": {
              "type": "number"
            },
            "birthDate": {
              "type": "string",
              "format": "date"
            },
            "lastLogin": {
              "type": "string",
              "format": "date-time"
            },
            "address": {
              "type": "string"
            },
            "emptyHash": {
              "type": "object"
            },
            "fines": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "emptyHashes": {
              "type": "array",
              "items": {
                "type": "object"
              }
            },
            "matrix": {
              "type": "array",
              "items": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              }
            },
            "friends": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "birthDate": {
                    "type": "string",
                    "format": "date"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            },
            "car": {
              "type": "object",
              "properties": {
                "brand": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
Type inference
value inferred type format notes
"some string" string
"1991-08-29" string date Format must match exactly, otherwise it is considered a regular string
"2015-06-10T13:23:30-08:00" string date-time Format must match exactly, otherwise it is considered a regular string
true / false boolean
[...] array Type for the array values is inferred by checking on the first element
{...} object Types for the fields inside the object are checked recursively
null string
Optional fields

Fields are set as optional using the custom x-optional: true attribute.

When a fields is received in a message and then not received in a subsequent message, it is considered optional as the presence of that field cannot be guaranteed.

When a field is received in a message and was never previously received, it is also considered optional.

Running locally

Install dependencies

go mod download

Load environmental variables

source .env.dev
go run main.go -f fixtures/test/yaml_config.yml

You can also fetch the configuration from a url

go run main.go -u https://raw.githubusercontent.com/uesteibar/scribano/master/fixtures/test/yaml_config.yml

Running on docker

docker run -e PG_URL='postgresql://postgres:postgres@localhost:5433/asyncapi' uesteibar/scribano ./scribano -u https://raw.githubusercontent.com/uesteibar/scribano/master/fixtures/test/yaml_config.yml
Running tests

Start the rabbitmq server

docker-compose up -d

Run the tests

make test

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

Directories

Path Synopsis
asyncapi
storage
db
web
api

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL