generate: Add support for import configuration examples with the id attribute

.changes/unreleased/FEATURES-20250616-181322.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'generate: Added support for defining import example file (`import-by-string-id.tf`) using Terraform configuration and the `id` attribute'
+time: 2025-06-16T18:13:22.627319-04:00
+custom:
+    Issue: "472"

README.md

@@ -223,15 +223,16 @@ For examples:
 > **NOTE:** In the following conventional paths for examples, `<data source name>` and `<resource name>` include the provider prefix as well, but the provider prefix is **NOT** included in`<function name>`.
 > For example, the data source [`caller_identity`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) in the `aws` provider would have an "example" conventional path of: `examples/data-sources/aws_caller_identity/data-source.tf`
 
-| Path                                                                      | Description                       |
-|---------------------------------------------------------------------------|-----------------------------------|
-| `examples/`                                                               | Root of examples                  |
-| `examples/provider/provider.tf`                                           | Provider example config           |
-| `examples/data-sources/<data source name>/data-source.tf`                 | Data source example config        |
-| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config |
-| `examples/functions/<function name>/function.tf`                          | Function example config           |
-| `examples/resources/<resource name>/resource.tf`                          | Resource example config           |
-| `examples/resources/<resource name>/import.sh`                            | Resource example import command   |
+| Path                                                                      | Description                          |
+|---------------------------------------------------------------------------|--------------------------------------|
+| `examples/`                                                               | Root of examples                     |
+| `examples/provider/provider.tf`                                           | Provider example config              |
+| `examples/data-sources/<data source name>/data-source.tf`                 | Data source example config           |
+| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config    |
+| `examples/functions/<function name>/function.tf`                          | Function example config              |
+| `examples/resources/<resource name>/resource.tf`                          | Resource example config              |
+| `examples/resources/<resource name>/import.sh`                            | Resource example import command      |
+| `examples/resources/<resource name>/import-by-string-id.tf`               | Resource example import by id config |
 
 #### Migration
 
@@ -280,31 +281,33 @@ using the following data fields and functions:
 
 ##### Provider Fields
 
-|                   Field |  Type  | Description                                                                               |
-|------------------------:|:------:|-------------------------------------------------------------------------------------------|
-|          `.Description` | string | Provider description                                                                      |
-|           `.HasExample` |  bool  | Is there an example file?                                                                 |
-|          `.ExampleFile` | string | Path to the file with the terraform configuration example                                 |
-|         `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
-|    `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`)                                |
+| Field                   | Type   | Description                                                                               |
+|-------------------------|--------|-------------------------------------------------------------------------------------------|
+| `.Description`          | string | Provider description                                                                      |
+| `.HasExample`           | bool   | Is there an example file?                                                                 |
+| `.ExampleFile`          | string | Path to the file with the terraform configuration example                                 |
+| `.ProviderName`         | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
+| `.ProviderShortName`    | string | Short version of the rendered provider name (ex. `random`)                                |
 | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
-|       `.SchemaMarkdown` | string | a Markdown formatted Provider Schema definition                                           |
+| `.SchemaMarkdown`       | string | a Markdown formatted Provider Schema definition                                           |
 
 ##### Managed Resource / Ephemeral Resource / Data Source Fields
 
-|                   Field |  Type  | Description                                                                               |
-|------------------------:|:------:|-------------------------------------------------------------------------------------------|
-|                 `.Name` | string | Name of the resource/data-source (ex. `tls_certificate`)                                  |
-|                 `.Type` | string | Either `Resource` or `Data Source`                                                        |
-|          `.Description` | string | Resource / Data Source description                                                        |
-|           `.HasExample` |  bool  | Is there an example file?                                                                 |
-|          `.ExampleFile` | string | Path to the file with the terraform configuration example                                 |
-|            `.HasImport` |  bool  | Is there an import file?                                                                  |
-|           `.ImportFile` | string | Path to the file with the command for importing the resource                              |
-|         `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
-|    `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`)                                |
+| Field                   | Type   | Description                                                                               |
+|-------------------------|--------|-------------------------------------------------------------------------------------------|
+| `.Name`                 | string | Name of the resource/data-source (ex. `tls_certificate`)                                  |
+| `.Type`                 | string | Either `Resource` or `Data Source`                                                        |
+| `.Description`          | string | Resource / Data Source description                                                        |
+| `.HasExample`           | bool   | Is there an example file?                                                                 |
+| `.ExampleFile`          | string | Path to the file with the terraform configuration example                                 |
+| `.HasImport`            | bool   | Is there an import shell file? (`terraform import` shell example)                         |
+| `.ImportFile`           | string | Path to the file with the command for importing the resource                              |
+| `.HasImportIDConfig`    | bool   | Is there an import terraform config file? (`import` block example with `id`)              |
+| `.ImportIDConfigFile`   | string | Path to the file with the Terraform configuration for importing the resource by `id`      |
+| `.ProviderName`         | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
+| `.ProviderShortName`    | string | Short version of the rendered provider name (ex. `random`)                                |
 | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
-|       `.SchemaMarkdown` | string | a Markdown formatted Resource / Data Source Schema definition                             |
+| `.SchemaMarkdown`       | string | a Markdown formatted Resource / Data Source Schema definition                             |
 
 ##### Provider-defined Function Fields
 

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar

@@ -144,6 +144,8 @@ HasExample: true
 ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
 HasImport: true
 ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
+HasImportIDConfig: true
+ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
 ProviderName: terraform-provider-scaffolding
 ProviderShortName: scaffolding
 RenderedProviderName: terraform-provider-scaffolding
@@ -191,7 +193,7 @@ codefile:
 Import is supported using the following syntax:
 
 ```shell
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 ```
 
 tffile:
@@ -305,6 +307,8 @@ HasExample: {{.HasExample}}
 ExampleFile: {{.ExampleFile}}
 HasImport: {{.HasImport}}
 ImportFile: {{.ImportFile}}
+HasImportIDConfig: {{.HasImportIDConfig}}
+ImportIDConfigFile: {{.ImportIDConfigFile}}
 ProviderName: {{.ProviderName}}
 ProviderShortName: {{.ProviderShortName}}
 RenderedProviderName: {{.RenderedProviderName}}
@@ -371,12 +375,21 @@ data "scaffolding_example" "example" {
 provider "scaffolding" {
   # example configuration here
 }
--- examples/resources/scaffolding_example/resource.tf --
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/resources/scaffolding_example/import.sh --
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
+-- examples/resources/scaffolding_example/resource.tf --
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
 -- internal/provider/example_data_source.go --
 // Copyright (c) HashiCorp, Inc.
 // SPDX-License-Identifier: MPL-2.0

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar

@@ -144,6 +144,8 @@ HasExample: true
 ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
 HasImport: true
 ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
+HasImportIDConfig: true
+ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
 ProviderName: terraform-provider-scaffolding
 ProviderShortName: scaffolding
 RenderedProviderName: terraform-provider-scaffolding
@@ -191,7 +193,7 @@ codefile:
 Import is supported using the following syntax:
 
 ```shell
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 ```
 
 tffile:
@@ -305,6 +307,8 @@ HasExample: {{.HasExample}}
 ExampleFile: {{.ExampleFile}}
 HasImport: {{.HasImport}}
 ImportFile: {{.ImportFile}}
+HasImportIDConfig: {{.HasImportIDConfig}}
+ImportIDConfigFile: {{.ImportIDConfigFile}}
 ProviderName: {{.ProviderName}}
 ProviderShortName: {{.ProviderShortName}}
 RenderedProviderName: {{.RenderedProviderName}}
@@ -371,12 +375,21 @@ data "scaffolding_example" "example" {
 provider "scaffolding" {
   # example configuration here
 }
--- examples/resources/scaffolding_example/resource.tf --
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/resources/scaffolding_example/import.sh --
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
+-- examples/resources/scaffolding_example/resource.tf --
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
 -- internal/provider/example_data_source.go --
 // Copyright (c) HashiCorp, Inc.
 // SPDX-License-Identifier: MPL-2.0

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar

@@ -122,6 +122,29 @@ resource "scaffolding_example" "example" {
 ### Read-Only
 
 - `id` (String) Example identifier
+
+## Import
+
+Import is supported using the following syntax:
+
+In Terraform v1.5.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `id` attribute, for example:
+
+```terraform
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+```
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+terraform import scaffolding_example.example "id-123"
+```
 -- examples/README.md --
 # Examples
 
@@ -140,6 +163,17 @@ data "scaffolding_example" "example" {
 provider "scaffolding" {
   # example configuration here
 }
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+-- examples/resources/scaffolding_example/import.sh --
+terraform import scaffolding_example.example "id-123"
 -- examples/resources/scaffolding_example/resource.tf --
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar

@@ -193,6 +193,8 @@ HasExample: true
 ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
 HasImport: true
 ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
+HasImportIDConfig: true
+ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
 ProviderName: terraform-provider-scaffolding
 ProviderShortName: scaffolding
 RenderedProviderName: terraform-provider-scaffolding
@@ -240,7 +242,7 @@ codefile:
 Import is supported using the following syntax:
 
 ```shell
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 ```
 
 tffile:
@@ -453,6 +455,8 @@ HasExample: {{.HasExample}}
 ExampleFile: {{.ExampleFile}}
 HasImport: {{.HasImport}}
 ImportFile: {{.ImportFile}}
+HasImportIDConfig: {{.HasImportIDConfig}}
+ImportIDConfigFile: {{.ImportIDConfigFile}}
 ProviderName: {{.ProviderName}}
 ProviderShortName: {{.ProviderShortName}}
 RenderedProviderName: {{.RenderedProviderName}}
@@ -581,11 +585,20 @@ provider "scaffolding" {
   # example configuration here
 }
 -- examples/resources/scaffolding_example/resource.tf --
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/resources/scaffolding_example/import.sh --
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 -- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf --
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar

@@ -193,11 +193,20 @@ resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf --
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/resources/scaffolding_example/import.sh --
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 -- schema.json --
 {
     "format_version": "1.0",

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar

@@ -192,6 +192,8 @@ HasExample: true
 ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
 HasImport: true
 ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
+HasImportIDConfig: true
+ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
 ProviderName: terraform-provider-scaffolding
 ProviderShortName: Scaffolding
 RenderedProviderName: Scaffolding
@@ -239,7 +241,7 @@ codefile:
 Import is supported using the following syntax:
 
 ```shell
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 ```
 
 tffile:
@@ -452,6 +454,8 @@ HasExample: {{.HasExample}}
 ExampleFile: {{.ExampleFile}}
 HasImport: {{.HasImport}}
 ImportFile: {{.ImportFile}}
+HasImportIDConfig: {{.HasImportIDConfig}}
+ImportIDConfigFile: {{.ImportIDConfigFile}}
 ProviderName: {{.ProviderName}}
 ProviderShortName: {{.ProviderShortName}}
 RenderedProviderName: {{.RenderedProviderName}}
@@ -584,11 +588,20 @@ resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf --
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 -- examples/resources/scaffolding_example/import.sh --
-terraform import scaffolding_example.example
+terraform import scaffolding_example.example "id-123"
 -- schema.json --
 {
     "format_version": "1.0",

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar

@@ -192,6 +192,23 @@ resource "scaffolding_example" "example" {
 ### Read-Only
 
 - `id` (String) Example identifier
+
+## Import
+
+Import is supported using the following syntax:
+
+In Terraform v1.5.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `id` attribute, for example:
+
+```terraform
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
+```
 -- expected-ephemeral-resource.md --
 ---
 # generated by https://github.com/hashicorp/terraform-plugin-docs
@@ -250,6 +267,15 @@ output "test" {
 provider "scaffolding" {
   # example configuration here
 }
+-- examples/resources/scaffolding_example/import-by-string-id.tf --
+import {
+  to = scaffolding_example.example
+  id = "id-123"
+}
+
+resource "scaffolding_example" "example" {
+  configurable_attribute = "some-value"
+}
 -- examples/resources/scaffolding_example/resource.tf --
 resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"