openapi

Documentation

Index

• Constants
• func ProviderOpenAPI(providerName string) (*schema.Provider, error)
• type ClientOpenAPI
• type PluginConfigSchema
• type PluginConfigSchemaV1
  • func NewPluginConfigSchemaV1(services map[string]*ServiceConfigV1) *PluginConfigSchemaV1
  • func (p *PluginConfigSchemaV1) GetAllServiceConfigurations() (ServiceConfigurations, error)
  • func (p *PluginConfigSchemaV1) GetServiceConfig(providerName string) (ServiceConfiguration, error)
  • func (p *PluginConfigSchemaV1) GetVersion() (string, error)
  • func (p *PluginConfigSchemaV1) Marshal() ([]byte, error)
  • func (p *PluginConfigSchemaV1) Validate() error
• type PluginConfiguration
  • func NewPluginConfiguration(providerName string) (*PluginConfiguration, error)
• type ProviderClient
  • func (o *ProviderClient) Delete(resource SpecResource, id string) (*http.Response, error)
  • func (o *ProviderClient) Get(resource SpecResource, id string, responsePayload interface{}) (*http.Response, error)
  • func (o *ProviderClient) Post(resource SpecResource, requestPayload interface{}, responsePayload interface{}) (*http.Response, error)
  • func (o *ProviderClient) Put(resource SpecResource, id string, requestPayload interface{}, ...) (*http.Response, error)
• type ServiceConfigV1
  • func NewServiceConfigV1(swaggerURL string, insecureSkipVerifyEnabled bool) *ServiceConfigV1
  • func (s *ServiceConfigV1) GetSchemaPropertyConfiguration(schemaPropertyName string) ServiceSchemaPropertyConfiguration
  • func (s *ServiceConfigV1) GetSwaggerURL() string
  • func (s *ServiceConfigV1) IsInsecureSkipVerifyEnabled() bool
• type ServiceConfiguration
• type ServiceConfigurations
• type ServiceSchemaPropertyConfiguration
• type ServiceSchemaPropertyConfigurationV1
  • func (s ServiceSchemaPropertyConfigurationV1) GetDefaultValue() (string, error)
• type ServiceSchemaPropertyExternalConfigurationV1
• type SpecAnalyser
  • func CreateSpecAnalyser(specAnalyserVersion SpecAnalyserVersion, openAPIDocumentURL string) (SpecAnalyser, error)
• type SpecAnalyserVersion
• type SpecBackendConfiguration
• type SpecHeaderParam
  • func (h SpecHeaderParam) GetHeaderTerraformConfigurationName() string
• type SpecHeaderParameters
• type SpecResource
• type SpecSecurity
• type SpecSecurityDefinition
• type SpecSecurityDefinitions
• type SpecSecurityScheme
• type SpecSecuritySchemes
• type SpecV2Resource

Constants

const OpenAPIPluginConfigurationFileName = "terraform-provider-openapi.yaml"

OpenAPIPluginConfigurationFileName defines the file name used for the OpenAPI plugin configuration

Functions

func ProviderOpenAPI

func ProviderOpenAPI(providerName string) (*schema.Provider, error)

ProviderOpenAPI returns a terraform.ResourceProvider.

Types

type ClientOpenAPI

type ClientOpenAPI interface {
	Post(resource SpecResource, requestPayload interface{}, responsePayload interface{}) (*http.Response, error)
	Put(resource SpecResource, id string, requestPayload interface{}, responsePayload interface{}) (*http.Response, error)
	Get(resource SpecResource, id string, responsePayload interface{}) (*http.Response, error)
	Delete(resource SpecResource, id string) (*http.Response, error)
}

ClientOpenAPI defines the behaviour expected to be implemented for the OpenAPI Client used in the Terraform OpenAPI Provider

type PluginConfigSchema

type PluginConfigSchema interface {
	// Validate performs a check to confirm that the schema content is correct
	Validate() error
	// GetServiceConfig returns the service configuration for a given provider name
	GetServiceConfig(providerName string) (ServiceConfiguration, error)
	// GetAllServiceConfigurations returns all the service configuration
	GetAllServiceConfigurations() (ServiceConfigurations, error)
	// GetVersion returns the plugin configuration version
	GetVersion() (string, error)
	// Marshal serializes the value provided into a YAML document
	Marshal() ([]byte, error)
}

PluginConfigSchema defines the interface/expected behaviour for PluginConfigSchema implementations.

type PluginConfigSchemaV1

type PluginConfigSchemaV1 struct {
	Version  string                      `yaml:"version"`
	Services map[string]*ServiceConfigV1 `yaml:"services"`
}

PluginConfigSchemaV1 defines PluginConfigSchema version 1 Configuration example: version: '1' services:

monitor:
  swagger-url: http://monitor-api.com/swagger.json
  insecure_skip_verify: true
cdn:
  swagger-url: https://cdn-api.com/swagger.json
vm:
  swagger-url: http://vm-api.com/swagger.json

func NewPluginConfigSchemaV1

func NewPluginConfigSchemaV1(services map[string]*ServiceConfigV1) *PluginConfigSchemaV1

NewPluginConfigSchemaV1 creates a new PluginConfigSchemaV1 that implements PluginConfigSchema interface

func (*PluginConfigSchemaV1) GetAllServiceConfigurations

func (p *PluginConfigSchemaV1) GetAllServiceConfigurations() (ServiceConfigurations, error)

GetAllServiceConfigurations returns all the service configuration

func (*PluginConfigSchemaV1) GetServiceConfig

func (p *PluginConfigSchemaV1) GetServiceConfig(providerName string) (ServiceConfiguration, error)

GetServiceConfig returns the configuration for the given provider name

func (*PluginConfigSchemaV1) GetVersion

func (p *PluginConfigSchemaV1) GetVersion() (string, error)

GetVersion returns the plugin configuration version

func (*PluginConfigSchemaV1) Marshal

func (p *PluginConfigSchemaV1) Marshal() ([]byte, error)

Marshal serializes the value provided into a YAML document

func (*PluginConfigSchemaV1) Validate

func (p *PluginConfigSchemaV1) Validate() error

Validate makes sure that schema data is correct

type PluginConfiguration

type PluginConfiguration struct {
	// ProviderName defines the <provider_name> (should match the provider name of the terraform provider binary; terraform-provider-<provider_name>)
	ProviderName string
	// Configuration defines the reader that contains the plugin's external configuration (located at ~/.terraform.d/plugins)
	// If the plugin configuration file is not present the OTF_VAR_<provider_name>_SWAGGER_URL environment variable will
	// be required when invoking the openapi provider.
	// If at runtime both the OTF_VAR_<provider_name>_SWAGGER_URL as well as the plugin configuration file are present
	// the former takes preference. This allows the user to override the url specified in the configuration file with
	// the value provided in the OTF_VAR_<provider_name>_SWAGGER_URL
	Configuration io.Reader
}

PluginConfiguration defines the OpenAPI plugin's configuration

func NewPluginConfiguration

func NewPluginConfiguration(providerName string) (*PluginConfiguration, error)

NewPluginConfiguration creates a new PluginConfiguration

type ProviderClient

type ProviderClient struct {
	// contains filtered or unexported fields
}

ProviderClient defines a client that is configured based on the OpenAPI server side documentation The CRUD operations accept an OpenAPI operation which defines among other things the security scheme applicable to the API when making the HTTP request

func (*ProviderClient) Delete

func (o *ProviderClient) Delete(resource SpecResource, id string) (*http.Response, error)

Delete performs a DELETE request to the server API based on the resource configuration and the resource instance id passed in

func (*ProviderClient) Get

func (o *ProviderClient) Get(resource SpecResource, id string, responsePayload interface{}) (*http.Response, error)

Get performs a GET request to the server API based on the resource configuration and the resource instance id passed in

func (*ProviderClient) Post

func (o *ProviderClient) Post(resource SpecResource, requestPayload interface{}, responsePayload interface{}) (*http.Response, error)

Post performs a POST request to the server API based on the resource configuration and the payload passed in

func (*ProviderClient) Put

func (o *ProviderClient) Put(resource SpecResource, id string, requestPayload interface{}, responsePayload interface{}) (*http.Response, error)

Put performs a PUT request to the server API based on the resource configuration and the payload passed in

type ServiceConfigV1

type ServiceConfigV1 struct {
	// SwaggerURL defines where the swagger is located
	SwaggerURL string `yaml:"swagger-url"`
	// InsecureSkipVerify defines whether the internal http client used to fetch the swagger file should verify the server cert
	// or not. This should only be used purposefully if the server is using a self-signed cert and only if the server is trusted
	InsecureSkipVerify bool `yaml:"insecure_skip_verify"`
	// SchemaConfigurationV1 represents the list of schema property configurations
	SchemaConfigurationV1 []ServiceSchemaPropertyConfigurationV1 `yaml:"schema_configuration"`
}

ServiceConfigV1 defines configuration for the service provider

func NewServiceConfigV1

func NewServiceConfigV1(swaggerURL string, insecureSkipVerifyEnabled bool) *ServiceConfigV1

NewServiceConfigV1 creates a new instance of NewServiceConfigV1 struct with the values provided

func (*ServiceConfigV1) GetSchemaPropertyConfiguration

func (s *ServiceConfigV1) GetSchemaPropertyConfiguration(schemaPropertyName string) ServiceSchemaPropertyConfiguration

GetSchemaPropertyConfiguration returns the external configuration for the given schema property name; nil is returned if no such property exists

func (*ServiceConfigV1) GetSwaggerURL

func (s *ServiceConfigV1) GetSwaggerURL() string

GetSwaggerURL returns the URL where the service swagger doc is exposed

func (*ServiceConfigV1) IsInsecureSkipVerifyEnabled

func (s *ServiceConfigV1) IsInsecureSkipVerifyEnabled() bool

IsInsecureSkipVerifyEnabled returns true if the given provider's service configuration has InsecureSkipVerify enabled; false otherwise

type ServiceConfiguration

type ServiceConfiguration interface {
	// GetSwaggerURL returns the URL where the service swagger doc is exposed
	GetSwaggerURL() string
	// IsInsecureSkipVerifyEnabled returns true if the given provider's service configuration has InsecureSkipVerify enabled; false
	// otherwise
	IsInsecureSkipVerifyEnabled() bool
	// GetSchemaPropertyConfiguration returns the schema configuration for the given schemaPropertyName
	GetSchemaPropertyConfiguration(schemaPropertyName string) ServiceSchemaPropertyConfiguration
}

ServiceConfiguration defines the interface/expected behaviour for ServiceConfiguration implementations.

type ServiceConfigurations

type ServiceConfigurations map[string]ServiceConfiguration

ServiceConfigurations contains the map with all service configurations

type ServiceSchemaPropertyConfiguration

type ServiceSchemaPropertyConfiguration interface {
	GetDefaultValue() (string, error)
}

ServiceSchemaPropertyConfiguration defines the behaviour expected for the service schema property configuration

type ServiceSchemaPropertyConfigurationV1

type ServiceSchemaPropertyConfigurationV1 struct {
	SchemaPropertyName    string                                       `yaml:"schema_property_name"`
	DefaultValue          string                                       `yaml:"default_value"`
	ExternalConfiguration ServiceSchemaPropertyExternalConfigurationV1 `yaml:"schema_property_external_configuration"`
}

ServiceSchemaPropertyConfigurationV1 implements the ServiceSchemaPropertyConfiguration and defines the different fields supported that enable the configuration of the provider's properties via the terraform-provider-openapi.yaml plugin config file

func (ServiceSchemaPropertyConfigurationV1) GetDefaultValue

func (s ServiceSchemaPropertyConfigurationV1) GetDefaultValue() (string, error)

GetDefaultValue returns the default value for the schema property configuration. The following logic defines the preference when deciding what should be the default value of the property: - if the property does not have external configuration ('schema_property_external_configuration') and it does have a 'default_value' is set, then value used will be the one specified in the 'default_value' field - if the property has both the external configuration ('schema_property_external_configuration') and the 'default_value' fields set:

• If 'file' field is populated then:
• If the 'content_type' is raw the contents of the 'file' will be used as default value
• If the 'content_type' is json then the content of the 'file' must be json structure and the default value used will be the one defined in the 'key_name'
• An error is thrown otherwise

type ServiceSchemaPropertyExternalConfigurationV1

type ServiceSchemaPropertyExternalConfigurationV1 struct {
	// File defines the file containing the value of the schema property
	File string `yaml:"file"`
	// KeyName defines the specific key to look for within the File (only when json content type)
	KeyName string `yaml:"key_name"`
	// ContentType defines the type of content the File has
	ContentType string `yaml:"content_type"` // Currently supported types: raw, json
}

ServiceSchemaPropertyExternalConfigurationV1 defines the external configuration for a provider property.

type SpecAnalyser

type SpecAnalyser interface {
	// GetTerraformCompliantResources defines the method that is meant to discover the paths from the OpenAPI document
	// that are considered Terraform compliant, returning a list of SpecResource or an error otherwise.
	GetTerraformCompliantResources() ([]SpecResource, error)
	// GetSecurity returns a SpecSecurity based on the security defined in the OpenAPI document
	GetSecurity() SpecSecurity
	// GetAllHeaderParameters returns SpecHeaderParameters containing all the headers defined in the OpenAPI document. This
	// enabled the OpenAPI provider to expose the headers as configurable properties available in the OpenAPI Terraform
	// provider; so users can provide values for the headers that are meant to be sent along with the operations the headers
	// are defined in.
	GetAllHeaderParameters() (SpecHeaderParameters, error)
	// GetAPIBackendConfiguration encapsulates all the information related to the backend in the OpenAPI doc
	// (e,g: host, protocols, etc) which is then used in the ProviderClient to communicate with the API as specified in
	// the configuration.
	GetAPIBackendConfiguration() (SpecBackendConfiguration, error)
}

SpecAnalyser analyses the swagger doc and provides helper methods to retrieve all the end points that can be used as terraform resources. These endpoints have to meet certain criteria to be considered eligible resources as explained below: A resource is considered any end point that meets the following:

• POST operation on the root path (e,g: api/users)
• GET operation on the instance path (e,g: api/users/{id}). Other operations like DELETE, PUT are optional

In the example above, the resource name would be 'users'. Versioning is also supported, thus if the endpoint above had been api/v1/users the corresponding resouce name would have been 'users_v1'

func CreateSpecAnalyser

func CreateSpecAnalyser(specAnalyserVersion SpecAnalyserVersion, openAPIDocumentURL string) (SpecAnalyser, error)

CreateSpecAnalyser is a factory method that returns the appropriate implementation of SpecAnalyser depending upon the openApiSpecAnalyserVersion passed in. Currently only OpenAPI v2 version is supported but this constructor is ready to handle new implementations such as v3 when the time comes

type SpecAnalyserVersion

type SpecAnalyserVersion string

SpecAnalyserVersion defines the type for versions supported in the SpecAnalyser

type SpecBackendConfiguration

type SpecBackendConfiguration interface {
	// contains filtered or unexported methods
}

SpecBackendConfiguration defines the behaviour related to the OpenAPI doc backend configuration

type SpecHeaderParam

type SpecHeaderParam struct {
	Name          string
	TerraformName string
}

SpecHeaderParam defines the properties for a Header Parameter

func (SpecHeaderParam) GetHeaderTerraformConfigurationName

func (h SpecHeaderParam) GetHeaderTerraformConfigurationName() string

GetHeaderTerraformConfigurationName returns the terraform compliant name of the header. If the header TerraformName field is populated it takes preference over the name field.

type SpecHeaderParameters

type SpecHeaderParameters []SpecHeaderParam

SpecHeaderParameters groups a list of SpecHeaderParam

type SpecResource

type SpecResource interface {
	// contains filtered or unexported methods
}

SpecResource defines the behaviour related to terraform compliant OpenAPI Resources.

type SpecSecurity

type SpecSecurity interface {
	// GetAPIKeySecurityDefinitions returns all the OpenAPI security definitions from the OpenAPI document and translates those
	// into SpecSecurityDefinitions
	GetAPIKeySecurityDefinitions() (*SpecSecurityDefinitions, error)
	// GetGlobalSecuritySchemes returns all the global security schemes from the OpenAPI document and translates those
	// into SpecSecuritySchemes
	GetGlobalSecuritySchemes() (SpecSecuritySchemes, error)
}

SpecSecurity defines the behaviour related to OpenAPI security. This interface serves as a translation between the OpenAPI document and the security spec that will be used by the OpenAPI Terraform provider

type SpecSecurityDefinition

type SpecSecurityDefinition interface {
	// contains filtered or unexported methods
}

SpecSecurityDefinition defines the behaviour expected for security definition implementations. This interface creates an abstraction between the swagger security definitions and the openapi provider removing dependencies in external libraries

type SpecSecurityDefinitions

type SpecSecurityDefinitions []SpecSecurityDefinition

SpecSecurityDefinitions groups a list of SpecSecurityDefinition

type SpecSecurityScheme

type SpecSecurityScheme struct {
	Name string
}

SpecSecurityScheme defines a security scheme. This struct serves as a translation between the OpenAPI document and the scheme that will be used by the OpenAPI Terraform provider when making API calls to the backend

type SpecSecuritySchemes

type SpecSecuritySchemes []SpecSecurityScheme

SpecSecuritySchemes groups a list of SpecSecurityScheme

type SpecV2Resource

type SpecV2Resource struct {
	Name   string
	Region string
	// Path contains the full relative path to the resource e,g: /v1/resource
	Path string
	// SpecSchemaDefinition definition represents the representational state (aka model) of the resource
	SchemaDefinition spec.Schema
	// RootPathItem contains info about the resource root path e,g: /resource, including the POST operation used to create instances of this resource
	RootPathItem spec.PathItem
	// InstancePathItem contains info about the resource's instance /resource/{id}, including GET, PUT and REMOVE operations if applicable
	InstancePathItem spec.PathItem

	// SchemaDefinitions contains all the definitions which might be needed in case the resource schema contains properties
	// of type object which in turn refer to other definitions
	SchemaDefinitions map[string]spec.Schema
}

SpecV2Resource defines a struct that implements the SpecResource interface and it's based on OpenAPI v2 specification