anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myruleset.yaml
anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myruleset.zip
anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myrulesetfolder
Validating and Publishing Custom Rulesets
After you create a custom ruleset:
-
Validate the ruleset.
-
Generate the documentation for the ruleset.
-
Publish your custom ruleset to Exchange as a new asset.
For an example sequence of commands to validate and publish your rulesets, see Example Command Sequence to Validate and Publish.
As with custom code and configurations, rulesets are not considered supported MuleSoft products. For help with issues with custom rulesets, post an issue in the AMF Custom Validator Github repository. |
Validate the Ruleset
To validate your governance ruleset as you create it and before you publish it, use the following command:
governance:ruleset:validate
> governance:ruleset:validate [flags] <governance-ruleset>
This command validates the ruleset definitions passed using the governance-ruleset
parameter. You can pass one of the following as the governance-ruleset
parameter:
-
A ruleset definition YAML file
-
A ZIP file that contains an API project with an
exchange.json
file that specifies the ruleset as the main file -
A folder that contains an API project with an
exchange.json
file that specifies the ruleset as the main file
This command accepts only the default flags.
Example commands:
Example output for a valid ruleset:
Ruleset User/myuser/myrulesetfolder/myruleset.yaml Ruleset conforms with Dialect
Example output for a nonvalid ruleset:
Ruleset does not conform with Dialect ModelId: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml Profile: Validation Profile 1.0 Conforms: false Number of results: 1 Level: Violation - Constraint: http://a.ml/amf/default_document#/declarations/profileNode_profile_required_validation Message: Property 'profile' is mandatory Severity: Violation Target: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml#/encodes Property: http://schema.org/name Range: [(3,0)-(11,19)] Location: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml
Generate the Ruleset Documentation
Use the following command to generate a documentation ZIP file for a ruleset YAML file. Upload the resulting documentation ZIP file along with its associated ruleset file using the anypoint-cli-v4 exchange asset upload
command.
governance:document
> governance:document [flags] <ruleset> <doc-file>
This command creates the documentation for the API Governance ruleset definition ZIP file specified in ruleset
. It puts the documentation in the doc-file
ZIP file for you to upload and publish to Exchange.
This command accepts only the default flags.
Example command:
anypoint-cli-v4 governance:document /myrulesetfolder/mynewruleset.yaml /myrulesetfolder/ruleset.doc.zip
Example output:
validation name [ 'security-fields-operation-empty' ] validation name [ 'access-tokens-oauth2-cleartext' ] validation name [ 'insecure-oauth2-grants' ] validation name [ 'api-keys-in-cookie' ] validation name [ 'api-keys-in-query' ] validation name [ 'api-keys-in-header' ] validation name [ 'api-negotiates-authentication' ] validation name [ 'insecure-basic-auth' ] validation name [ 'bearer-token-cleartext' ] validation name [ 'http-token-cleartext' ] validation name [ 'oauth1-deprecated' ] validation name [ 'oauth2-redirections-non-encrypted' ] validation name [ 'unknown-security-scheme' ] validation name [ 'valid-server-urltemplate' ] validation name [ 'valid-oauth2-redirection-urls' ] Saving to myRulesetFolder/ruleset.doc.zip
Publish the Custom Ruleset
You can publish (upload) a ruleset and its documentation to Exchange using the following Anypoint CLI command.
exchange:asset:upload
> exchange:asset:upload [flags] <assetIdentifier>
This command uploads a rest-api, soap-api, http-api, raml-fragment, custom, app, template, example, policy, extension, external-library, connector asset, or ruleset using the ID passed in <assetIdentifier>
.
Use the following format for the assetIdentifier argument:
([groupID]/)assetID/version
If group_id is not specified, it defaults to the currently selected organization ID.
Flag | Description | ||
---|---|---|---|
|
Asset name (required if no pom file is specified) For example:
|
||
|
Asset description |
||
|
Asset properties For example:
|
||
|
Asset file, identified as To send multiple files, you typically use the same flag multiple times:
An exception to this is when you upload ruleset documentation with a ruleset. Both sets of classifiers and packaging options must be entered in a single
Examples: To upload a POM file and a RAML specification:
To upload a ruleset and its documentation:
|
||
|
Asset type Required if no file is specified. Supported Values:
If it is uploaded, the type is inferred from the classifier of the file. Depending on the type of asset, some possible classifier values are:
|
||
|
Categories (value should be a string in JSON format) '{"key": "value"}' For example: '{"Department": "IT"}' |
||
|
Fields (value should be a string in JSON format) '{"key": "value"}' For example: '{"releaseDate": "2020-01-01T20:00:00.000Z"}' |
||
|
Keywords (comma-separated) For example:
|
||
|
Tags (comma-separated) For example:
|
||
|
Asset dependencies (comma-separated) For example:
|
||
|
Asset status Supported Values:
Default value:
|
Example Command Sequence to Validate and Publish
Use the following example sequence to get started validating your ruleset, generating its documentation, and uploading both to Exchange. Replace the details, such as the folder name, ruleset file name, and ruleset documentation ZIP file name, with your own.
anypoint-cli-v4 governance:ruleset:validate /myRulesetFolder/mynewruleset.yaml (1)
anypoint-cli-v4 governance:document /myRulesetFolder/mynewruleset.yaml /myRulesetFolder/ruleset.doc.zip (2)
anypoint-cli-v4 exchange asset upload my-auth-best-practices/1.0.0 --name "My Best Practices Ruleset" --description "This ruleset enforces my best practices for APIs." --files='{"ruleset.yaml":"/myRulesetFolder/mynewruleset.yaml", "docs.zip": "/myRulesetFolder/ruleset.doc.zip"}' (3)
1 | Validates the ruleset locally. The ruleset file is mynewruleset.yaml in the /myRulesetFolder/ folder. |
2 | Generates the documentation ZIP file, ruleset.doc.zip , for the ruleset myruleset.yaml . Both files are in the /myRulesetFolder/ folder. |
3 | Uploads the ruleset, mynewruleset.yaml , and its documentation, ruleset.doc.zip . Both files are in the /myRulesetFolder/ folder. |