🛠️ SonarAsyncAPI (Rules)

Warning

This project is deprecated and no longer maintained. No new features, bug fixes or releases are planned. Issues and pull requests may not be reviewed. Existing releases remain available, but use them at your own risk.

This repository contains a set of custom SonarQube rules specifically designed to analyze and improve the quality of AsyncAPI specifications. By integrating these rules, teams can ensure best practices, maintainability, and consistency in their API definitions.

This repository is intended for community use, it can be modified and adapted without commercial use. If you need a version, support or help for your enterprise or project, please contact us 📧 devrel@apiaddicts.org

💡 If you have an idea for a rule but you are not sure that everyone needs it you can implement a custom rule available only for you.

🙌 Join the doSonarApi Adopters list

📢 If doSonarApi is part of your organization's toolkit, we kindly encourage you to include your company's name in our Adopters list. 🙏 This not only significantly boosts the project's visibility and reputation but also represents a small yet impactful way to give back to the project.

Organization	Description of Use / Referenc
CloudAppi	Apification and generation of microservices
Madrid Digital	Generation of microservices
Apiquality	Generation of microservices

👩🏽‍💻 Contribute to ApiAddicts

We're an inclusive and open community, welcoming you to join our effort to enhance ApiAddicts, and we're excited to prioritize tasks based on community input, inviting you to review and collaborate through our GitHub issue tracker.

Feel free to drop by and greet us on our GitHub discussion or Discord chat. You can also show your support by giving us some GitHub stars ⭐️, or by following us on Twitter, LinkedIn, and subscribing to our YouTube channel! 🚀

📑 Getting started

🔍 Configure scanner

Maven plugin

Configure properties

In pom.xml configure:

    <properties>
        <!-- Optional, When is set only the language specified is analyzed -->
        <sonar.language>asyncapi</sonar.language>
        <!-- Optional, Default value is src/main,pom.xml -->
        <sonar.sources>.</sonar.sources>
    </properties>

Run scanner

mvn sonar:sonar -Dsonar.host.url=<HOST> -Dsonar.login=<KEY>

External sonar-scanner

Install sonar-scanner

Download the sonar-scanner from https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/ and make it accessible.

Configure properties

In sonar-project.properties (file in root project folder) configure:

# must be unique in a given SonarQube instance
sonar.projectKey=test:test
# this is the name and version displayed in the SonarQube UI. Was mandatory prior to SonarQube 6.1.
sonar.projectName=AsyncAPI plugin tests
sonar.projectVersion=1.0-SNAPSHOT

# Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.
# This property is optional if sonar.modules is set.
sonar.sources=.

# Encoding of the source code. Default is default system encoding
sonar.sourceEncoding=UTF-8
# Select the language to use for analysis
sonar.language=asyncapi

▶️ Run scanner

sonar-scanner -Dsonar.host.url=<HOST> -Dsonar.login=<KEY>

✅ Compatibility

This plugin is supported by SonarQube versions greater or equal to 6.7.4

Explicit compatibility versions tested

Version
6.7.4
7.9-community
8.3-community

📑 Current Rules

• AAR001MandatoryHttpsProtocolCheck: Server must use a secure protocol (https, wss, amqps, etc).
• AAR008DefinedServerCheck: The AsyncAPI document must define at least one server in the 'servers' object.
• AAR009DeclaredTagCheck: Operation must declare at least one tag.
• AAR010DocumentedTagCheck: Tag should have a 'description' field.
• AAR011DefinedLicenseCheck: The 'info' object must contain a 'license' field.
• AAR012DeclaredOperationIDCheck: Operation must declare an 'operationId'.
• AAR013DuplicateOperationIDCheck: There cannot be two operations with the same operationId.
• AAR015UndefiendContactCheck: The 'info' object must contain a 'contact' section.
• AAR016ContactPropertiesCheck: The 'contact' object must include 'name', 'url', and 'email' fields.
• AAR017UndefinedUrlLicenseCheck: The 'license' object must include a 'url' field.
• AAR018SecuritySchemasCheck: The security scheme must be among those allowed by the organization and must be complete.
• AAR019IDSchemasCheck: The AsyncAPI document should define an 'id' field.
• AAR021ProvideOpSummaryCheck: Operation must have a 'summary' field.
• AAR022DescriptionDiffersSummaryCheck: The 'description' field must not be identical to the 'summary' field.
• AAR024MessageValidationCheck: All messages sent and received must comply with the message schema specified in the documentation.
• AAR026MessageSchemasCheck: Message schemas are recommended to be found in components.
• AAR029MandatoryDescriptionCheck: Each channel and each operation must have a description that explains its purpose and function.
• AAR031MessageExamplesCheck: All examples in message object should follow payload and headers schemas.
• AAR032NumericParameterIntegrityCheck: Numeric property should have at least one of: minimum, maximum, format, enum, or const restriction.
• AAR033StringParameterIntegrityCheck: String property should have at least one of: minLength, maxLength, pattern, enum, const, or format restriction.
• AAR034NumericFormatCheck: Numeric property must specify a valid 'format' (int32, int64, float, double).
• AAR035MessageTitleCheck: Message should have a 'title' field.
• AAR036BadDescriptionCheck: The description must begin with a capital letter and end with a period.
• AAR037BindingVersionCheck: Binding must specify a 'bindingVersion' field.
• AAR040DefinedChannelServersCheck: Channel references a server that is not defined in the 'servers' object.
• AAR041ComponetChannelServerCheck: Consider defining reusable server and channel references in 'components'.
• AAR042MessageIdentifierCheck: Message should have a 'messageId' field for unique identification.
• AAR043SecurityChannelCheck: Channel should define a security scheme in its operations or bindings.
• AAR044AvroNamespaceCheck: Avro record must declare a namespace field to avoid name collisions across services.
• AAR045AvroNamespaceNamingCheck: Avro namespace must follow lowercase dot notation, e.g. org.example.company.
• AAR046AvroRecordDocCheck: Avro record should include a doc description at the record level.
• AAR047AvroFieldDocCheck: Each Avro field should include a doc description.
• AAR048AvroNameNomenclatureCheck: Avro record and field names must match the Avro naming specification (^[A-Za-z_][A-Za-z0-9_]*$).
• AAR049AvroDefaultNullCheck: Avro fields with a nullable union type must define default: null for backward-compatible schema evolution.
• AAR050InfoTitleRequiredCheck: The info.title field must exist and not be empty.
• AAR051OperationIdCamelCaseCheck: The operationId must be present and follow camelCase naming convention.
• AAR052AvroNamespacePatternCheck: The namespace of a named Avro schema (record, enum or fixed) is required and must follow the corporate pattern.
• AAR053ChannelNamingConventionCheck: The channel name must follow the corporate topic naming convention <cod_poaps>.<classification>.<domain>.<origin>.<scope>[.<version>].
• AAR054ClassificationValidValuesCheck: The channel name's classification segment (2nd segment) must be cdc, cmd or sys.
• AAR055XPayloadReferencesWellFormedCheck: The x-payload-references extension, wherever it appears, must have subject, ref and referenceName on every item.
• AAR056AvroSchemaFormatCheck: When schemaFormat indicates Avro, it must be exactly application/vnd.apache.avro;version=1.9.0.
• AAR057ErrorTopicDocumentedCheck: At least one channel must be documented as an error topic following <topicOriginal>.[<consumerGroup>.]error.<n>.
• AAR058RetryTopicNamingConventionCheck: If a channel name contains .retry., it must follow <topicOriginal>.<consumerGroup>.retry.<n>.
• AAR059AvroRecordNameCamelCaseCheck: The name field of every Avro record, including records nested inside fields[].type, unions, arrays and maps, must be in CamelCase with an uppercase first letter.
• AAR060ContentTypeAvroCheck: A message's contentType (and the document-level defaultContentType) must match application/*+avro.
• AAR061ProcessorFunctionNamePairedCheck: Every x-scs-function-name must be paired one-to-one between a producing (publish/send) and a consuming (subscribe/receive) operation.
• AAR062SubscribeGroupRequiredCheck: Each consuming operation (v2 subscribe, v3 action: receive) must declare a consumer group via x-scs-group or bindings.kafka.groupId.
• AAR063AsyncAPIVersionAllowedCheck: The root asyncapi version must be one of the versions allowed by the organization (configurable via allowedVersions; default 2.6.0).
• AAR064KafkaProtocolRequiredCheck: In the Kafka context, the server protocol must be kafka or kafka-ssl (not https, wss, etc.).

💛 Sponsors