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:
resource "petstore_pet" "my_pet" { id = 10 name = "doggie" photo_urls = [ "...", ]}
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.