# AsyncAPI Codegen
[](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:
```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 \
--progtype provider
```
### Markdown documentation
This command will generate documentation for utilizers. The entire spec is output in one big markdown file.
```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
--markdown
```
## License
GPLv2
Raw data
{
"_id": null,
"home_page": "http://github.com/pearmaster/asyncapi-codgen",
"name": "asyncapi-codegen",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Jacob Brunson",
"author_email": "pypi@jacobbrunson.com",
"download_url": "https://files.pythonhosted.org/packages/5a/c6/67ccd1dd9cd43e5b6b2b9f4808d101a31b2738ae2593fdeeb865a67e6e63/asyncapi-codegen-0.5.0.tar.gz",
"platform": null,
"description": "# AsyncAPI Codegen\n\n[](https://dl.circleci.com/status-badge/redirect/gh/pearmaster/asyncapi-codegen/tree/master)\n\n`asyncapi-codegen` interprets an AsyncAPI spec and generates code and documentation accordingly. Only MQTT is supported.\n\nThere are two parts to this:\n\n * Interpret the AsyncAPI spec into Python classes in ways that makes it easier to use.\n * Use Jinja2 templates to create the code.\n\n### Terminology\n\nWith 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.\n\nA **provider** is the MQTT service that provides functionality. The AsyncAPI spec describes the behavior of the provider.\nA **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.\n\n## Supported Languages\n\n| Lanaguage | MQTT Library | JSON Library | JSON Schema Library |\n|------------|-------------------|-----------------|----------------------------------|\n| C++ | Mosquitto Client | rapidjson | Built-in via json-schema-codegen |\n| Python | Paho MQTT | Python built-in | None |\n\nFeatures:\n\n| Feature | Python | C++ |\n|-------------------------------|------------|-----|\n| Enforces JSON Schema | No | Yes |\n\n## Documentation Formats\n\nFormats:\n\n * Markdown (with significant HTML), suitable for display on GitLab.\n \n\n#### Output files\n\nThe generator creates the following types of output files:\n\n * **client interface**. This is the main interface for publishing or subscribing to messages.\n * **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.\n * **parameters**. These are just schema objects.\n * **messages**. Currently, these are just schema objects. However, in the future these objects will also take protocol-specific message bindings.\n * **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).\n\nGenerated code files should be annotated for **doxygen** document generation, or at least that is the goal.\n\n### Installation\n\n```sh\npip3 install asyncapi-codegen\n```\n\n### Python requirements for running code generator\n\nSee also [requirements.txt](./requirements.txt)\n\n* python 3.10\n* jinja2\n* stringcase\n* json-schema-codegen\n* pyyaml\n\n## Python Code Generation\n\n### Requirements for the generated python code\n\n* python 3.7\n* parse\n* paho-mqtt\n\n## C++ Code Generation \n\n### Requirements for the generated C++ code\n\n* boost (boost::optional and boost::variant among others)\n* rapidjson 1.1\n* C++11\n\n## Using Docker\n\n### Utilizer code\n\nTo 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. \n\nWhen the YAML uses the words \"publish\" and \"subscribe\", the utilizer will perform those MQTT actions.\n\n```sh\ndocker run --rm -t \\\n -v $(pwd)/examples:/specs \\\n -v $(pwd)/output:/output \\\n --user $UID:$GID \\\n docker.io/pearmaster/asyncapi-codegen:latest \\\n --yaml /specs/streetlights-mqtt.yml \\\n --name Streetlights \\\n --cpp\n```\n\n### Provider code\n\nIf you'd like instead to generate C++ code for the provider, you can append `--progtype provider` to the docker command to look like:\n\n```sh\ndocker run --rm -t \\\n -v $(pwd)/examples:/specs \\\n -v $(pwd)/output:/output \\\n --user $UID:$GID \\\n docker.io/pearmaster/asyncapi-codegen:latest \\\n --yaml /specs/streetlights-mqtt.yml \\\n --name Streetlights \\\n --cpp \\\n --progtype provider\n```\n\n### Markdown documentation\n\nThis command will generate documentation for utilizers. The entire spec is output in one big markdown file. \n\n```sh\ndocker run --rm -t \\\n -v $(pwd)/examples:/specs \\\n -v $(pwd)/output:/output \\\n --user $UID:$GID \\\n docker.io/pearmaster/asyncapi-codegen:latest \\\n --yaml /specs/streetlights-mqtt.yml \\\n --name Streetlights\n --markdown\n```\n\n## License\n\nGPLv2\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "Generate C++ for an AsyncAPI Specification",
"version": "0.5.0",
"project_urls": {
"Homepage": "http://github.com/pearmaster/asyncapi-codgen"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e0cfc5dcd47df0857b8bde4fdb28b9ba9e66bb304d2aacd7c438033e76c81f1",
"md5": "442782386199a7b1f7cfaafd34afd604",
"sha256": "5ac26f0b4d5c8f44edb0be0c544d85482626482a1a559a68295b9427f9b5c4af"
},
"downloads": -1,
"filename": "asyncapi_codegen-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "442782386199a7b1f7cfaafd34afd604",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 39027,
"upload_time": "2023-05-01T00:38:41",
"upload_time_iso_8601": "2023-05-01T00:38:41.092471Z",
"url": "https://files.pythonhosted.org/packages/6e/0c/fc5dcd47df0857b8bde4fdb28b9ba9e66bb304d2aacd7c438033e76c81f1/asyncapi_codegen-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ac667ccd1dd9cd43e5b6b2b9f4808d101a31b2738ae2593fdeeb865a67e6e63",
"md5": "145e0a6a072759395614f866f0ab3574",
"sha256": "46a3ffdbda5dca492be095c5e0bda02784a7bb54f6626e361ff3f268f9763c5c"
},
"downloads": -1,
"filename": "asyncapi-codegen-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "145e0a6a072759395614f866f0ab3574",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29566,
"upload_time": "2023-05-01T00:38:43",
"upload_time_iso_8601": "2023-05-01T00:38:43.488239Z",
"url": "https://files.pythonhosted.org/packages/5a/c6/67ccd1dd9cd43e5b6b2b9f4808d101a31b2738ae2593fdeeb865a67e6e63/asyncapi-codegen-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-01 00:38:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pearmaster",
"github_project": "asyncapi-codgen",
"lcname": "asyncapi-codegen"
}
JSON
