Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Investigation on using Async-api for clamp messaging doc.

Tool:

  • Java AsyncAPI: This tool stores modules, which simplifies interacting with AsyncAPI in jvm ecosystem.
  • MultiAPI Generator

    SCS MultiApi Plugin: This is a plugin designed to help developers automatizing the creation of code classes from YML files based on AsyncApi and OpenAPI. It…

  • ZenWave SDK: DDD and API-First for Event-Driven Microservices
  • Springwolf: Automated documentation for event-driven applications built with Spring Boot

SCS MultiApi Plugin

This is a plugin designed to help developers automatizing the creation of code classes from YML files based on AsyncApi and OpenAPI. It is presented in 2 flavours Maven and Gradle (MPL-2.0 license).

This plugin allows developers to automatize the creation of code classes for REST and Kafka connections, based on YML files under the AsyncApi and OpenApi specifications. In the latter case, many of the configuration options and classes that are generated are based on reimplementation or modification of the OpenAPI Generator models and template designs.

The generation of the REST and Kafka connections is independent each other and could be used only one, or both at the same time.

Link: (https://github.com/sngular/scs-multiapi-plugin)

Below the plugin for policy-clamp-models:

Code Block
languagexml
titlepom
            <plugin>
                <groupId>com.sngular</groupId>
                <artifactId>scs-multiapi-maven-plugin</artifactId>
                <version>5.3.5</version>
                <executions>
                    <execution>
                        <id>asyncapi</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>asyncapi-generation</goal>
                        </goals>
                        <configuration>
                            <specFiles>
                                <specFile>
                                    <filePath>${project.basedir}/src/main/resources/asyncapi/asyncapi.yaml</filePath>
                                    <supplier>
                                        <ids>sendMessage</ids>
                                        <modelPackage>org.onap.policy.clamp.models.acm.messages.kafka.participant</modelPackage>
                                    </supplier>
                                    <consumer>
                                        <ids>receiveMessage</ids>
                                        <modelPackage>org.onap.policy.clamp.models.acm.messages.kafka.participant</modelPackage>
                                    </consumer>
                                </specFile>
                            </specFiles>
                            <generatedSourcesFolder>sources-generated</generatedSourcesFolder>
                        </configuration>
                    </execution>
                </executions>
            </plugin>


Below the models/src/main/resources/asyncapi/asyncapi.yaml for ParticipantRegister and ParticipantRegisterAck messages.

Code Block
languageyml
titleasyncapi.yaml
asyncapi: 2.0.0
info:
  title: Account Service
  version: '1.0.0'
  description: Manages user accounts in the system.

servers:
  production:
    url: kafka:9092
    protocol: kafka
    description: kafka broker

channels:
  policy-acm-participant:
    publish:
      operationId: sendMessage
      message:
        $ref: '#/components/messages/ParticipantRegisterAck'

  policy-acm-acruntime:
    subscribe:
      operationId: receiveMessage
      message:
        $ref: '#/components/messages/ParticipantRegister'

components:
  messages:

    ParticipantRegister:
      name: ParticipantRegister
      title: ParticipantRegister
      summary: Register a participant
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ParticipantRegister'

    ParticipantRegisterAck:
      name: ParticipantRegisterAck
      title: ParticipantRegisterAck
      summary: Send message back from a registered participant
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ParticipantRegisterAck'

  schemas:

    ParticipantRegister:
      type: object
      properties:
        messageType:
          description: "Message Type"
          $ref:  '#/components/schemas/ParticipantMessageType'
          default: 'PARTICIPANT_REGISTER'
        messageId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: dateTime
        participantId:
          type: string
          format: uuid
        participantSupportedElementType:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantSupportedElementType'

    ParticipantSupportedElementType:
      type: object
      properties:
        id:
          type: string
          format: uuid
        typeName:
          type: string
        typeVersion:
          type: string

    ParticipantRegisterAck:
      type: object
      properties:
        messageType:
          description: "Message Type"
          $ref:  '#/components/schemas/ParticipantMessageType'
          default: 'PARTICIPANT_REGISTER_ACK'
        responseTo:
          type: string
          format: uuid
        timestamp:
          type: string
          format: dateTime
        participantId:
          type: string
          format: uuid
        Message:
          type: string

    ParticipantMessageType:
      type: string
      enum:
        - PARTICIPANT_STATUS
        - PARTICIPANT_STATE_CHANGE
        - AUTOMATION_COMPOSITION_DEPLOY
        - AUTOMATION_COMPOSITION_STATE_CHANGE
        - PARTICIPANT_REGISTER
        - PARTICIPANT_REGISTER_ACK
        - PARTICIPANT_DEREGISTER
        - PARTICIPANT_DEREGISTER_ACK
        - PARTICIPANT_PRIME
        - PARTICIPANT_PRIME_ACK
        - AUTOMATION_COMPOSITION_DEPLOY_ACK
        - AUTOMATION_COMPOSITION_STATECHANGE_ACK
        - PARTICIPANT_STATUS_REQ
        - PROPERTIES_UPDATE
        - PARTICIPANT_RESTART
        - AUTOMATION_COMPOSITION_MIGRATION


  • the plugin generates model classes with builder support; is mandatory create the bean with the builder;
  • there is no support for java.util.UUID and java.time.Instant;
  • appliesTo method have to be refactored;

ZenWave SDK

ZenWave SDK is a configurable and extensible toolkit for Domain Driven Design (DDD) and API-First that can generate code from a mix of different models including (MIT license):

  • ZDL Domain Language
  • AsyncAPI
  • OpenAPI

Link: (https://github.com/zenwave360/zenwave-sdk)

Springwolf

 It documents asynchronous APIs using the AsyncAPI specification. (Apache License 2.0).

springwolf-ui adds a web UI, much like that of Springfox, and allows easy publishing of auto-generated payload examples.

Using @AsyncListener and @AsyncPublisher any protocol can be documented, although the binding in the AsyncAPI document will remain empty. 
The protocols with native support come along with a @_ProtocolName_Binding annotation to define protocol specific properties.

Library:

Code Block
languagexml
titlepom
        <dependency>
            <groupId>io.github.springwolf</groupId>
            <artifactId>springwolf-core</artifactId>
            <version>0.16.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.springwolf</groupId>
            <artifactId>springwolf-kafka</artifactId>
            <version>0.16.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.springwolf</groupId>
            <artifactId>springwolf-ui</artifactId>
            <version>0.16.0</version>
        </dependency>

Properties file:

Code Block
languageyml
titleapplication.yaml
# Springwolf Configuration
springwolf:
  docket:
    base-package: org.onap.policy.clamp.acm.runtime
    info:
      title: ACM Runtime
      version: 1.0.0
      description: ACM Runtime Documentation using Springwolf

# Springwolf Kafka Configuration
    servers:
      kafka:
        protocol: kafka
        url: ${topicServer:kafka:9092}

  plugin:
    kafka:
      scanner:
        kafka-listener:
          enabled: false

Example Java code:

Code Block
languagejava
titleSupervisionParticipantHandler class
    @AsyncListener(
        operation = @AsyncOperation(
            channelName = "policy-acruntime-participant",
            description = "Listener ParticipantRegister",
            payloadType = ParticipantRegister.class
        )
    )
    @KafkaAsyncOperationBinding
    public void handleParticipantMessage(ParticipantRegister participantRegisterMsg) {
       -----
    }


http://localhost:6969/onap/policy/clamp/acm/springwolf/asyncapi-ui.html

Image Added

Springwolf Kafka Plugin

Automated documentation for Spring Boot application with Kafka consumers.

This plugin generates an AsyncAPI document from @KafkaListener methods. (ACM-Runtime do not using @KafkaListener).