Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pearmaster/asyncapi-codegen

Uses an AsyncAPI 2.0 spec to generate C++ code
https://github.com/pearmaster/asyncapi-codegen

Last synced: 2 days ago
JSON representation

Uses an AsyncAPI 2.0 spec to generate C++ code

Host: GitHub
URL: https://github.com/pearmaster/asyncapi-codegen
Owner: pearmaster
License: gpl-2.0
Created: 2019-11-10T04:20:00.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2023-05-01T23:09:07.000Z (over 1 year ago)
Last Synced: 2024-08-03T16:08:57.798Z (4 months ago)
Language: Jinja
Size: 130 KB
Stars: 6
Watchers: 1
Forks: 2
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# AsyncAPI Codegen

[![CircleCI](https://dl.circleci.com/status-badge/img/gh/pearmaster/asyncapi-codegen/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/pearmaster/asyncapi-codegen/tree/master)

`asyncapi-codegen` interprets an AsyncAPI spec and generates code and documentation accordingly. Only MQTT is supported.

There are two parts to this:

* Interpret the AsyncAPI spec into Python classes in ways that makes it easier to use.
* Use Jinja2 templates to create the code.

### Terminology

With pub/sub architecture, the broker is a server and everything is a client to it. As such, is is useful to define the general nature of clients to differentiate roles between clients.

A **provider** is the MQTT service that provides functionality. The AsyncAPI spec describes the behavior of the provider.
A **utilizer** is the MQTT client that consumes the functionality. When the AsyncAPI spec uses "publish" and "subscribe" terms, it is the utilizer that does the described action.

## Supported Languages

| Lanaguage | MQTT Library | JSON Library | JSON Schema Library |
|------------|-------------------|-----------------|----------------------------------|
| C++ | Mosquitto Client | rapidjson | Built-in via json-schema-codegen |
| Python | Paho MQTT | Python built-in | None |

Features:

| Feature | Python | C++ |
|-------------------------------|------------|-----|
| Enforces JSON Schema | No | Yes |

## Documentation Formats

Formats:

* Markdown (with significant HTML), suitable for display on GitLab.

#### Output files

The generator creates the following types of output files:

* **client interface**. This is the main interface for publishing or subscribing to messages.
* **servers**. Represents a connection to a server. Currently, only _unauthenticated MQTT_ connections are supported. A _server object_ is provided to a _client interface_ to establish the connection to the broker/server.
* **parameters**. These are just schema objects.
* **messages**. Currently, these are just schema objects. However, in the future these objects will also take protocol-specific message bindings.
* **schemas**. These are structures that always enforce schema compliance and provide (de-)serialization methods to rapidjson Value objects (which can thus be used to create JSON strings).

Generated code files should be annotated for **doxygen** document generation, or at least that is the goal.

### Installation

```sh
pip3 install asyncapi-codegen
```

### Python requirements for running code generator

See also [requirements.txt](./requirements.txt)

* python 3.10
* jinja2
* stringcase
* json-schema-codegen
* pyyaml

## Python Code Generation

### Requirements for the generated python code

* python 3.7
* parse
* paho-mqtt

## C++ Code Generation

### Requirements for the generated C++ code

* boost (boost::optional and boost::variant among others)
* rapidjson 1.1
* C++11

## Using Docker

### Utilizer code

To generate utilizer/client C++ code for an AsyncAPI spec, you could run this docker command, carefully adjusting the volume mounting to the directory containing the specs and the directory for the output.

When the YAML uses the words "publish" and "subscribe", the utilizer will perform those MQTT actions.

```sh
docker run --rm -t \
-v $(pwd)/examples:/specs \
-v $(pwd)/output:/output \
--user $UID:$GID \
docker.io/pearmaster/asyncapi-codegen:latest \
--yaml /specs/streetlights-mqtt.yml \
--name Streetlights \
--cpp
```

### Provider code

If you'd like instead to generate C++ code for the provider, you can append `--progtype provider` to the docker command to look like:

### Markdown documentation

This command will generate documentation for utilizers. The entire spec is output in one big markdown file.

## License

GPLv2