# Resource Configuration

## Resource documentation

Speakeasy automatically generates provider and resource documentation that is compliant with the [public Terraform Registry requirements](https://developer.hashicorp.com/terraform/registry/providers/docs) via the HashiCorp-maintained [`terraform-plugin-docs`](https://github.com/hashicorp/terraform-plugin-docs) tool. Speakeasy runs `terraform-plugin-docs` at the end of successful generations or manually run via `go generate ./...`.

The public Terraform Registry and `terraform-plugin-docs` tool both follow specific file layout conventions.

For resources, the following file conventions are used:

The `terraform-plugin-docs` tool also supports its own advanced use case customization, such as custom templates. Refer to the [`terraform-plugin-docs` documentation](https://github.com/hashicorp/terraform-plugin-docs) for more information about those capabilities.

### Resource Description

The `x-speakeasy-entity-description` extension modifies the description of a Terraform data or managed resource. This is useful when augmenting the documentation for specific resources in an OpenAPI document. This documentation is expected to be in Markdown format. Use this extension alongside the `x-speakeasy-entity` extension.

In this example, an order managed resource will have `Manage a coffee order.` written as the description in the resource code for any consuming tools, including documentation written by `terraform-plugin-docs` into `docs/resources/order.md`:

```yaml
components:
  schemas:
    Order:
      description: An order helps you make coffee
      x-speakeasy-entity: Order
      x-speakeasy-entity-description: |
        Manage a coffee order.
```

### Resource Example

Example resource configuration is based on the OpenAPI Specification for API operation request and response data schemas. Speakeasy only generates example configuration for configurable properties. Example configuration values use the property `example` field when available or, as a fallback, use a generated value of the expected type following any `enum` or validation fields.

Fully customize the example resource configuration by using Speakeasy [code customization capabilities](/docs/customize/code/monkey-patching).

For example, to manually manage and update the example configuration for a managed resource:

* Edit root directory `.genignore` file with an entry for `examples/resources/{type}/resource.tf`
* Edit `examples/resources/{type}/resource.tf` as necessary
* Run `go generate ./...` or Speakeasy generation to update `docs/resources/{name}.md`

## Resource version

<Callout title="Use state upgraders sparingly" type="warning">
  State upgraders should be seldomly used for breaking schema type changes for existing state data. For adding/removing attributes, state upgraders are not needed and should be avoided.
</Callout>

The `x-speakeasy-entity-version` extension specifies the version of a given resource and should **only** be used if you need to write a state migrator, for instance, if you are changing the type of a field.

Terraform resource versions are zero-indexed and default to `0`. For your first breaking change requiring a state migrator, set `x-speakeasy-entity-version: 1`. Each state migrator function must migrate from the previous version of the state.

If this is set, a boilerplate state upgrader will be written and hooked into `internal/stateupgraders/your_resource_v1.go`. Please refer to the [Terraform documentation](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-upgrade) for guidance on writing a state migrator.