diff --git a/docs/terraform/common-troubleshooting.mdx b/docs/terraform/common-troubleshooting.mdx new file mode 100644 index 0000000..8fc392b --- /dev/null +++ b/docs/terraform/common-troubleshooting.mdx @@ -0,0 +1,116 @@ +--- +title: "Common Troubleshooting & Recipes" +description: "Learn about overcoming API design incompatibilities when generating Terraform providers with Speakeasy." +--- + +# Common Troubleshooting & Recipes + +## Overview + +When generating Terraform providers from OpenAPI specifications, you might +encounter cases where your API’s structure doesn’t naturally fit Terraform’s +resource-oriented approach. These differences typically occur because APIs +aren’t always designed with Terraform’s infrastructure management style in +mind. + +Speakeasy’s generator identifies these design differences and offers extensions +and customization options to address them. This enables you to produce +effective Terraform providers, even when your API doesn’t initially match +Terraform’s requirements, simplifying what might otherwise be challenging +configuration tasks. + +## Fixing Common API Issues + +### Impedance Mismatch Errors + +An impedance mismatch error happens when Speakeasy's generator finds properties +with different data types that need to be combined into one. This error means +the data types don't match up correctly across API operations (such as between +request and response data, or across different operations for the same entity), +which can cause problems in the Terraform provider that's being created. + +#### Common example + +A typical impedance mismatch scenario occurs in the following situation: + +- A request takes UUID string for task assignment: + +```json request.json +{ + "taskId": "12345", + "assignee": "user-uuid-1" +} +``` + +- The response returns a full user object for that assignee: + +```json response.json +{ + "taskId": "12345", + "assignee": { + "id": "user-uuid-1", + "name": "Alice Johnson" + } +} +``` + +When the generator attempts to merge these properties, it detects that it +cannot reconcile the different data types (string vs object) and yields an +impedance mismatch error. + +#### How to Fix the Problem + +Speakeasy includes built-in extensions to help fix impedance mismatch errors. +You can use these solutions to adjust either the request or the response data: + +**Option 1: Override the property name** + +Use `x-speakeasy-name-override` to give the mismatched properties different +names so they no longer attempt to merge: + +```yaml openapi.yaml +TaskRequest: + type: object + x-speakeasy-entity: Task + properties: + taskId: + type: string + assignee: + type: string + x-speakeasy-name-override: assigneeId # Override the name to avoid merging +``` + +With this approach, the additional data (stored in the `assignee` response +field) will still be available to Terraform consumers. However, there may be a +loss of drift detection when Terraform updates the resource’s state during the +read operation. + +Note: `x-speakeasy-name-override` can also be used to rename the conflicting +property (in this case, "assignee") in the response schema to achieve the same +effect. The key is to prevent a type collision between request and response. + +**Option 2: Ignore the mismatched property** + +Use `x-speakeasy-ignore` to exclude the problematic property from generation: + +```yaml openapi.yaml +TaskResponse: + type: object + x-speakeasy-entity: Task + properties: + taskId: + type: string + assignee: + type: object + properties: + id: + type: string + name: + type: string + x-speakeasy-ignore: true # Ignore this property in the response +``` + +This approach will resolve the impedance mismatch by removing the +conflicting property altogether. However, this also means that the +property will no longer be tracked in Terraform state. + diff --git a/docs/terraform/index.mdx b/docs/terraform/index.mdx index 16e4cc5..bb87047 100644 --- a/docs/terraform/index.mdx +++ b/docs/terraform/index.mdx @@ -48,6 +48,10 @@ Access advanced customization options for fine-grained control. Learn about supported OpenAPI schema keywords and their behavior. +### [Common Troubleshooting & Recipes](/docs/terraform/common-troubleshooting) + +Learn about overcoming API design incompatibilities when generating Terraform providers with Speakeasy. + ### [Configuration Reference](/docs/speakeasy-reference/generation/terraform-config) Complete reference for all available Terraform configuration options in the `gen.yaml` file.