Consider adding config options to override schema IR descriptions

[austinvalle]

Context

It would be useful to allow consumers of the CLI tool to be able to override the schema (IR) output after the OpenAPI spec has been processed. For example, an OpenAPI spec may not provide a description for an attribute, or the attribute description provided by the OpenAPI spec may not be written with Terraform nuance in mind.

Proposal

New Config Options

• For schema output that is not currently mapped from the OAS: add property's to control that output to the config under schema.

  resources:
  pet:
  # create, read, update, delete configuration
  # ...
  schema:
    description: Manages a pet resource

• For schema output that is currently mapped from the OAS: introduce an overrides property to the generator config under schema -> attributes

  resources:
  pet:
  # create, read, update, delete configuration
  # ...
  schema:
    description: Manages a pet resource
    attributes:
      overrides:
        id:
          description: My more important description of the identifier attribute

Syntax for attribute keys

overrides should also allow the config to describe attributes in a schema that are nested with something like a dot-separated syntax for the key. If no dot delimiters exist, we should assume it exists in the root of the schema:

resources:
  pet:
    # create, read, update, delete configuration
    # ...
    schema:
      description: Manages a pet resource
      attributes:
        overrides:
          id:
            description: My more important description of the root identifier attribute
          "nested_obj.id":
            description: My more important description of the nested identifier attribute

---

We should also consider adding a validation step to these overrides when the config is processed, as well as after the IR.json is created, with spec.Validate.

Other considerations

• We should determine how far we want the overriding to go. For example, should we allow rewriting types? Should we go no restrictions and allow full overriding of the IR?
• We should consider if we want to update schema -> attributes -> aliases to also support this dot-separated syntax

[bflad]

We should determine how far we want the overriding to go. For example, should we allow rewriting types? Should we go no restrictions and allow full overriding of the IR?

I'd say let's consider each potential override separately, waiting for real world use case(s). Descriptions was top of mind because API specification (or really any source) descriptions are likely not written with Terraform nuance in mind. Here's a very quick example: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role#managed_policy_arns

[github-actions[bot]]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.