為 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-element 的注釋，它指向定義示例的原始參數、有效負載、標頭等。 不幸的是，必須使用自定義 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