aws-cloudformation / cloudformation-cli

The CloudFormation Provider Development Toolkit allows you to author your own resource providers and modules that can be used by CloudFormation.
Apache License 2.0
318 stars 161 forks source link

Fix for docs generation when no items key for a schema property of array type is present. #1052

Closed mrinaudo-aws closed 9 months ago

mrinaudo-aws commented 9 months ago

Issue #, if available:

Description of changes: Fix for documentation generation when no items key for a schema property of array type is present. When running cfn generate, for example against a schema of a CloudFormation hook that is missing the items node for a given property of array type, while the schema validation succeeds, the document generation logic fails with a KeyError because it assumes the items node is present in the input data:

[...]
    if "$ref" in prop["items"]:
                 ~~~~^^^^^^^^^
KeyError: 'items'

This change fixes this behavior by leaving the schema validation unchanged, and by defaulting to an empty map for items if items itself is not present in the input data. Proposed changes also include a warning message for the user to take action if needed.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

brianlaoaws commented 9 months ago

Do you mind posting what the docs look like after this change?

mrinaudo-aws commented 9 months ago

Do you mind posting what the docs look like after this change?

@brianlaoaws sure - here is an example output whereas in the schema there were no items defined for a property, defaulting to _Type_: List of Map:

# (sample value omitted)

## Activation

To activate a hook in your account, use the following JSON as the `Configuration` request parameter for [`SetTypeConfiguration`](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html) API request.

### Configuration

<pre>
{
    "CloudFormationConfiguration": {
        "<a href="https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks-structure.html#hooks-hook-configuration" title="HookConfiguration">HookConfiguration</a>": {
            "<a href="https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks-structure.html#hooks-targetstacks" title="TargetStacks">TargetStacks</a>":  <a href="#footnote-1">"ALL" | "NONE"</a>,
            "<a href="https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks-structure.html#hooks-failuremode" title="FailureMode">FailureMode</a>": <a href="#footnote-1">"FAIL" | "WARN"</a> ,
            "<a href="https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks-structure.html#hooks-properties" title="Properties">Properties</a>" : {
                "<a href="(sample value omitted)" title="(sample value omitted)">(sample value omitted)</a>" : <i>[ Map, ... ]</i>
            }
        }
    }
}
</pre>

## Properties

#### (sample value omitted)

(sample value omitted)

_Required_: No

_Type_: List of Map

---

## Targets

* `(sample value omitted)`

---

<p id="footnote-1"><i> Please note that the enum values for <a href="https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks-structure.html#hooks-targetstacks" title="TargetStacks">
TargetStacks</a> and <a href="https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks-structure.html#hooks-failuremode" title="FailureMode">FailureMode</a>
might go out of date, please refer to their official documentation page for up-to-date values. </i></p>