Document Your Terraform Provider

An important aspect of Terraform providers is their documentation. Much of this documentation is generated from the provider using the standard terraform-plugin-docs tool (opens in a new tab) provided by HashiCorp. Terraform providers generated by Speakeasy will feed this tool information derived from your OpenAPI specification to make documentation.

You can control this documentation-creation process by providing good descriptions and examples in your OpenAPI spec. Whenever possible, though, Speakeasy will fill in your documentation and generate examples using defaults to allow you to get to a usable terraform apply as quickly as possible.

Usage Snippets

One of the primary means by which Terraform documentation is provided is through an example-usage snippet. These snippets provide a general overview of how to make use of the resources handled by your provider.

For example, the Swagger Pet Store example would generate a usage snippet for the pet resource like the following:

The id and name parameters are shown with the values given in example in the JSON Schema. The photo_urls parameter uses the default "..." value, a placeholder for when no example is given.

The optional category, status, and tags fields are omitted here. Optional fields are only shown when an example value is provided.

When documentation for the petstore_pet resource is generated and published to the Terraform Registry, this usage snippet will appear near the beginning.