{"id":13288448,"url":"https://github.com/NovatecConsulting/tc-asyncapi-directory","last_synced_at":"2025-03-10T06:33:31.313Z","repository":{"id":76666743,"uuid":"393430146","full_name":"NovatecConsulting/tc-asyncapi-directory","owner":"NovatecConsulting","description":"Angular application to display AsyncAPI specifications that were pulled from Kafka using Kafka Spring ","archived":false,"fork":false,"pushed_at":"2023-10-11T07:08:29.000Z","size":870,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-01-20T07:08:14.043Z","etag":null,"topics":["angular","asyncapi","kafka","pai"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NovatecConsulting.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-06T16:05:59.000Z","updated_at":"2023-08-06T11:58:51.000Z","dependencies_parsed_at":"2024-10-23T09:30:39.613Z","dependency_job_id":"4c630853-a300-4a44-bd5f-88e76bbe8b08","html_url":"https://github.com/NovatecConsulting/tc-asyncapi-directory","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NovatecConsulting%2Ftc-asyncapi-directory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NovatecConsulting%2Ftc-asyncapi-directory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NovatecConsulting%2Ftc-asyncapi-directory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NovatecConsulting%2Ftc-asyncapi-directory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NovatecConsulting","download_url":"https://codeload.github.com/NovatecConsulting/tc-asyncapi-directory/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242805420,"owners_count":20187995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","asyncapi","kafka","pai"],"created_at":"2024-07-29T16:56:54.757Z","updated_at":"2025-03-10T06:33:31.301Z","avatar_url":"https://github.com/NovatecConsulting.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":":toc:\n:toc-title:\n:toclevels: 2\n:sectnums:\n= AsyncAPI Directory\n\nIn large IT application landscapes, several teams usually work together. Several applications offer their interfaces to the outside world. Documenting these interfaces appropriately and making them available can become a challenge as the size of the IT infrastructure grows. For asynchronous applications in particular, new documentation requirements arise that could not previously be met by https://swagger.io/specification/[OpenAPI] (which has already established itself for synchronous applications). AsyncAPI has created a new possibility for this.\n\nThis project implements a prototype for the central provision of AsyncAPI definitions. For example, the AsyncAPI Directory could be used as follows: +\nMultiple teams developing different applications deploy their AsyncAPI definition so that it is stored in a Kafka Topic. The AsyncAPI Directory server lists all AsyncAPI definitions from this topic, including older versions. The development teams can view the corresponding AsyncAPI if needed and develop their application against it.\n\nThis idea of an API registry is already offered by https://www.apicur.io/[Apicurio]. However, since AsyncAPI is still a new standard, Apicurio does not yet provide a way to represent the AsyncAPI definitions in a human-readable way. https://github.com/Apicurio/apicurio-studio/issues/447[Work is in progress to fully support AsyncAPI].\n\nWhile this prototype uses only Kafka as a data store, other storage options are possible. For example, the AsyncAPI definitions could also be stored in a relational database.\n\nDeveloping new applications on a \"contract first\" basis offers several advantages, such as decoupling development processes across multiple teams. The provided AsyncAPI definitions could be used to create mockup services using a code generation tool, as already offered by https://microcks.io/[Microcks].\n\n\n== Quick Start\n\n. Start Kafka components using the cluster-setup script. The script will start the Docker containers and create the _asyncapi_ topic:\n+\n----\n./cluster-setup.sh\n----\n\n. Start KafkaApplication locally. Afterwards, its REST API will be accessible via port 8080.\n. Publish some testing data of AsyncAPI definitions:\n+\n----\n./test-data.sh\n----\n\n. Compile and start the Angular application:\n+\n----\ncd ./asyncapi-ui\nnpm install\nnpm install --save @asyncapi/react-component@next\nng serve\n----\n\n. Navigate to http://localhost:4200.\n\n== Preview\n\nimage::doc/asyncapi-directory-overview.png[]\nimage::doc/asyncapi-directory-details.png[]\n\n== Structure of this Prototype\nThis prototype uses the https://github.com/asyncapi/asyncapi-react[AsyncAPI React component]* that can be embedded within Angular applications. This makes the rendered AsyncAPI definitions look like what is offered by the https://www.asyncapi.com/[Playground]. +\nThe backend is written Kafka Spring, the frontend uses Angular. As soon as a new AsyncAPI definition is written into Kafka,\nthe server will consume the new definition and add it to its in-memory storage.\n\n*Components:*\n\n* *Kafka Broker*: the AsyncAPI definitions are stored within a Kafka topic\n* *Backend server*: listens for new definitions on the Kafka topic, caches them in-memory and offers a REST API\n* *Frontend application*: gets the AsyncAPI definitions from the server via REST calls; uses the AsyncAPI React component for rendering\n\n*Remark: At the moment, the React component is re-written in the https://github.com/asyncapi/asyncapi-react/tree/next[next-branch]. Since this branch contains all the new features, this prototype uses\nthe component from there.\n\n== Server REST API\nThe AsyncAPI server adds, gets and processes AsyncAPI definitions from Kafka. The REST API of the server provides some basic operations that are used by the Angular frontend application. Details about the endpoints can be found within the link:asyncapi-server-api.yaml[API documentation] which was written using OpenAPI/Swagger.\n\n\n== Defining AsyncAPIs\n=== Custom Extensions\n\nNearly every object within an AsyncAPI definition can be extended with https://www.asyncapi.com/docs/specifications/v2.0.0#specificationExtensions[specification extensions]:\n\n* definition of new fields by including an \"x-\" prefix\n* the custom fields are currently not rendered by the React component!\n\n=== Defining Kafka-Specific Properties with AsyncAPI\n*Server Configuration* +\nIt is currently not possible to configure the Kafka Broker with Kafka-specific\nbindings within an AsyncAPI definition. Kafka Topics are equivalent to AsyncAPI\nChannels. Therefore, the channel names correspond to the Kafka topic names.\nAdditional properties, e.g. the number of partitions or replication factors, could be configured by using custom extensions like described in paragraph 3.1.\n\n*Message Binding* +\nThe \"bindings\" property of the https://www.asyncapi.com/docs/specifications/v2.0.0#messageObject[message object] can be used to define keys of Kafka messages.\nFurther details are provided https://github.com/asyncapi/bindings/tree/master/kafka[here].\nSince \"key\" is defined to be a https://www.asyncapi.com/docs/specifications/v2.0.0#schemaObject[Schema Object], various additional properties can be specified and referenced.\n\n*Operation Binding* +\nThe \"bindings\" property can also be applied to the https://www.asyncapi.com/docs/specifications/v2.0.0#operationObject[operation object].\nIt can be used to define the _groupId_ and the _clientId_ of the consumer/producer.\nSince _groupId_ and _clientId_ are as well defined as https://www.asyncapi.com/docs/specifications/v2.0.0#schemaObject[Schema Objects], they could also be more complex than simple strings.\n\n\n== Official Extensions and Functionalities in Development\nThere are some official extensions and functionalities that are currently developed by the AsyncAPI Team. Some interesting projects are:\n\n*Diff Library* +\nThe https://github.com/asyncapi/diff[diff library] is in an early stage of development and aims to enable comparison and compatibility of API changes.\n\n*AsyncAPI Studio* +\nhttps://github.com/asyncapi/studio[Studio] is currently in an early stage of development and wants to offer an editor (similar to the playground) and potentially some other functionalities (?).\n\n*Modelina* +\nhttps://github.com/asyncapi/modelina[Modelina] is as well in an early stage of development.\nIt did not reach version 1.0.0 yet and therefore, breaking changes  are still possible.\nModelina SDK wants to enable generation of data models from JSON and AsyncAPI definitions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNovatecConsulting%2Ftc-asyncapi-directory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNovatecConsulting%2Ftc-asyncapi-directory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNovatecConsulting%2Ftc-asyncapi-directory/lists"}