README
¶
OpenAPI Provider Spec Generator
Terraform Provider Code Generation is currently in tech preview. If you have general questions or feedback about provider code generation, please create a new topic in the Plugin Development Community Forum.
Overview
The OpenAPI Provider Spec Generator is a CLI tool that transforms an OpenAPI 3.x Specification (OAS) into a Provider Code Specification.
A Provider Code Specification can be used to generate Terraform Provider code, for example, with the Plugin Framework Code Generator.
Documentation
Full usage info, examples, and config file documentation live on the HashiCorp developer site: https://developer.hashicorp.com/terraform/plugin/code-generation/openapi-generator
For more in-depth details about the design and internals of the OpenAPI Provider Spec Generator, see DESIGN.md.
Usage
Installation
You install a copy of the binary manually from the releases tab, or install via the Go toolchain:
go install github.com/hashicorp/terraform-plugin-codegen-openapi/cmd/tfplugingen-openapi@latest
Generate
The primary generate command requires a generator config and an OpenAPI 3.x specification:
tfplugingen-openapi generate \
--config <path/to/generator_config.yml> \
--output <output/for/provider_code_spec.json> \
<path/to/openapi_spec.json>
Examples
Example generator configs, OpenAPI specifications, and Provider Code Specification output can be found in the ./internal/cmd/testdata/ folder. Here is an example running petstore3, built from source:
go run ./cmd/tfplugingen-openapi generate \
--config ./internal/cmd/testdata/petstore3/generator_config.yml \
--output ./internal/cmd/testdata/petstore3/provider_code_spec.json \
./internal/cmd/testdata/petstore3/openapi_spec.json
License
Refer to Mozilla Public License v2.0.
Experimental Status
By using the software in this repository (the "Software"), you acknowledge that: (1) the Software is still in development, may change, and has not been released as a commercial product by HashiCorp and is not currently supported in any way by HashiCorp; (2) the Software is provided on an "as-is" basis, and may include bugs, errors, or other issues; (3) the Software is NOT INTENDED FOR PRODUCTION USE, use of the Software may result in unexpected results, loss of data, or other unexpected results, and HashiCorp disclaims any and all liability resulting from use of the Software; and (4) HashiCorp reserves all rights to make all decisions about the features, functionality and commercial release (or non-release) of the Software, at any time and without any obligation or liability whatsoever.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
config
Package config contains the types, parsing, and validation logic for the YAML generator configuration
|
Package config contains the types, parsing, and validation logic for the YAML generator configuration |
|
explorer
Package explorer contains the types and methods for relating OpenAPI operations to a set of Terraform Provider resource/data source actions (CRUD)
|
Package explorer contains the types and methods for relating OpenAPI operations to a set of Terraform Provider resource/data source actions (CRUD) |
|
log
Package log contains helper functions for structured logging
|
Package log contains helper functions for structured logging |
|
mapper
Package mapper includes the types and methods for mapping provider, resource, and data source types (explorer package) from an OpenAPI specification into Provider Code Specification.
|
Package mapper includes the types and methods for mapping provider, resource, and data source types (explorer package) from an OpenAPI specification into Provider Code Specification. |
|
mapper/attrmapper
Package attrmapper contains types and methods that provide an intermediate step between the OpenAPI schema types (libopenapi) and the Provider Code Specification types (terraform-plugin-codegen-spec).
|
Package attrmapper contains types and methods that provide an intermediate step between the OpenAPI schema types (libopenapi) and the Provider Code Specification types (terraform-plugin-codegen-spec). |
|
mapper/frameworkvalidators
Package frameworkvalidators contains functionality for mapping validations onto specification that uses terraform-plugin-framework-validators.
|
Package frameworkvalidators contains functionality for mapping validations onto specification that uses terraform-plugin-framework-validators. |
|
mapper/oas
Package oas contains the logic that determines how to map OpenAPI schemas to the intermediate attrmapper types.
|
Package oas contains the logic that determines how to map OpenAPI schemas to the intermediate attrmapper types. |