Specification Conformance
You can check for API specification conformance using a custom or MuleSoft-provided ruleset such as:
-
Anypoint Best Practices
-
Authentication Security Best Practices
-
OpenAPI Best Practices
-
AsyncAPI Best Practices
-
Required Examples
See Finding and Fixing Conformance Issues for an overview of ways to validate conformance and determine why conformance failed.
Validate API Specifications in Design Center
If your API is not governed using API Governance or if you want to see conformance issues directly in API Designer, you can validate your API in API Designer.
To validate APIs against governance rulesets in Design Center, add the rulesets as dependencies to API specifications in the Design Center API Designer text editor. After you add the rulesets, expand the Project Errors section to view conformance messages.
1 | Add rulesets to your API project as dependencies. |
2 | Expand the Project Errors section of the text editor to view nonconformance messages. |
3 | Click Validate for governance to initiate validation if Governance auto-validation is disabled. See Improving Ruleset Validation. |
4 | View conformance issues and filter by level of severity. |
Add Rulesets to Your Project
In API Designer, you can add governance rulesets to your API projects as Exchange dependencies.
If your API has been identified as governed through centralized API governance, a dot or warning icon appears on the Exchange dependencies icon to indicate you need to take action on the dependencies for this project. Click the Exchange dependencies icon to view and follow the interactive instructions to add rulesets as dependencies to your project.
Validate API Specifications Using Anypoint CLI
To validate against rulesets using CLI without using a governance profile, use the governance:api:validate
command.
governance:api:validate
> governance:api:validate <api-specification> [flags]
This command validates the API specification passed in api-specification
against specified rulesets.
This command has multi-option flags. When using multi-option flags in a command, either put the parameter before the flags or use "-- " (two dashes followed by a space) before the parameter. |
You can specify api-specification
as one of the following:
-
An API project ZIP file
-
An API project folder
-
An asset identifier for an API project, if the
--remote
flag is specified. An asset identifier is a group ID, asset ID, and version (GAV) that uniquely identifies each asset in Exchange.
You can specify rulesets against which to validate as follows:
-
To use an existing
exchange.json
file that defines your API project’s ruleset dependencies, ensure that theexchange.json
file is included in the folder or ZIP file that you specify inapi-specification
. If theexchange.json
file is present, the command downloads all of the ruleset dependencies and validates against those rulesets. The ruleset dependencies are present in theexchange.json
file only if dependencies are defined for that API project in API Designer. See Add Rulesets to Your Project. -
To validate directly against rulesets published in Exchange, use the
--remote-rulesets
flag. -
To validate against local rulesets, use the
--rulesets
flag.
Duplicate rulesets are not detected, so if you use more than one of the preceding ways of identifying rulesets in the same command execution, some rulesets might be validated multiple times. |
Besides the default flags, this command also accepts:
Flag | Description |
---|---|
|
Local ruleset definitions. The |
|
Remote ruleset definitions. The |
|
Flag to indicate that the validation should be done against a published API. The value passed in |
Example commands:
anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip
anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml
anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip --rulesets /MyRulesets/ruleset1.yaml /MyRulesets/ruleset2.yaml
anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip --remote-rulesets 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1
anypoint-cli-v4 governance:api:validate 8a840abd-e63a-4f8b-87ab-24052eda2017/order-api/1.0.0 --remote-rulesets 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1 --remote
Example output:
For a specification that is conformant to the ruleset:
Spec conforms with Ruleset
For a specification that is nonconformant to the ruleset:
Conforms: false Number of results: 3 (1) Functional Validations ---------------------- Constraint: http://a.ml/vocabularies/amf/core#declaration-not-found Severity: Violation Message: not supported scalar for documentation Target: null Range: [(6,3)-(6,3)] Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml Conformance Validations (2) ----------------------- Constraint: file:///exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.0/ruleset.yaml#/encodes/validations/api-must-have-documentation (3) Severity: Warning (4) Message: Provide the documentation for the API. (5) Target: amf://id#2 (6) Range: [(2,0)-(6,4)] (7) Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml (8) Constraint: file:///exchange_modules/8a840abd-e63a-4f8b-87ab-24052eda2017/best-practices-ruleset/1.0.0/bestpractices.yaml#/encodes/validations/api-must-have-documentation Severity: Violation Message: Provide the documentation for the API Target: amf://id#2 Range: [(2,0)-(6,4)] Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml
1 | Total of functional and conformance validation issues found |
2 | Conformance issues section |
3 | Ruleset and rule to which this set of issues applies |
4 | Severity level for the issue |
5 | Description of the issue |
6 | AMF model node ID; for information on the AMF model, see Creating Custom Governance Rulesets |
7 | Beginning line number and column and end line number and column in the API specification where the issue occurs, where column is the offset from the beginning of the line and numbering for the offset starts at 0 |
8 | The file in which the issue occurs, either the main file or one of its dependencies |
Get Exchange Asset Identifiers
To get the full asset identifier (group ID/asset ID/version) for Exchange assets:
-
If you are using Anypoint CLI, run the
exchange:asset:list
command. -
If you are using the Anypoint Platform web UI, select the asset in Exchange and copy the group ID and asset ID from the URL. Then, add the version node for the version you are viewing. For example, the asset identifier for the OpenAPI Best Practices ruleset in Exchange is
68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1
.
View Specification Conformance Issue Details in the Governance Report
To view specification conformance issues in the governance validation report:
-
In the API Governance console, select the Governed APIs tab.
-
If the API has a Not Conformant badge, click View Report for information about the conformance issue.
-
View all issues:
Click View Details for a ruleset the API is nonconformant to.
-
View issues for the specification only:
-
Select Specification in the Conformance Breakdown section of the report.
-
Click View Details for a ruleset the specification is nonconformant to.
-
-