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 that documentation.

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

Usage Snippets

One the primary means by which Terraform documentation is provided is through an example usage snippet. These can 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:

resource "petstore_pet" "my_pet" {
    id   = 10
    name = "doggie"
    photo_urls = [
        "...",
    ]
}

The "id", "name", and "photo_urls" parameters are shown. The "id" nad "name" are shown with the values given in the example from the JSON schema while "photo_urls" is using the default "..." value used as a placeholder when no example is given. Meanwhile, the "category", "status", and "tags" fields are omitted because they are optional. Optional fields are not usually shown unless an example value is provided.

This usage snippet would be included at the top of the generated documentation for the petstore_pet resource documentation, if it were to be published to the Terraform Registry.