创建API治理规则集

Question

我正在尝试为RAML创建规则集，以检查是否有用于uriParams的响应和描述的示例。

/example:    
      /{uriParams}:
        get:
          uriParameters:
          uriParams:
          description: Example description uriParams
          body:
          application/json:
          example: !include examples.example.json

为此，我创建了两个规则集，但它不起作用：

    response-example:
    message: Provide example.
    targetClass: apiContract.Example
    and:
       - propertyConstraints:
          apiContract.returns:
            atLeast:
                count: 1
                validation:
                 propertyConstraints:
                    apiContract.structuredValue:
                        pattern: "^!include"

  uri-descriptions:
    message: Provide descriptions.
    targetClass: apiContract.Parameter
    if:
      propertyConstraints:
        apiContract.Parameter:
          pattern: uri
    then:
      propertyConstraints:
        core.description:
          minCount: 1

Answer 1

检查示例是不平凡的。AMF (用于治理的RAML解析器)将它们解析为参数、有效负载、标头等的架构。只需澄清一个示例:假设您有一个Person类型的响应并有一个示例，该示例将从响应转移到Person类型。

幸运的是，AMF保留了一个名为tracked元素的注释，该注释指向定义示例的原始参数、有效载荷、标头等。不幸的是，必须使用自定义Rego代码检查这些元素是否相同。

下面是生成的规则集：

profile: My Ruleset

description: Example ruleset

violation:
  - provide-examples-on-payloads
  - provide-description-on-parameters

validations:
  provide-examples-on-payloads:
    message: Always include examples in request and response bodies
    targetClass: apiContract.Payload
    rego: |
      schema = find with data.link as $node["http://a.ml/vocabularies/shapes#schema"]

      nested_nodes[examples] with data.nodes as object.get(schema, "http://a.ml/vocabularies/apiContract#examples", [])

      examples_from_this_payload = { element |
        example = examples[_]
        sourcemap = find with data.link as object.get(example, "http://a.ml/vocabularies/document-source-maps#sources", [])
        tracked_element = find with data.link as object.get(sourcemap, "http://a.ml/vocabularies/document-source-maps#tracked-element", [])
        tracked_element["http://a.ml/vocabularies/document-source-maps#value"] = $node["@id"]
        element := example
      }

      $result := (count(examples_from_this_payload) > 0)

  provide-description-on-parameters:
    message: Always include examples in URI parameters
    targetClass: apiContract.Parameter
    if:
        propertyConstraints:
            apiContract.binding:
                in: ['path']
    
    then:
        propertyConstraints:
            core.description:
                minCount: 1