openapiterraformdocsgenerator

package
v0.30.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2020 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ArgumentReferenceTmpl = `` /* 883-byte string literal not displayed */

ArgumentReferenceTmpl contains the definition used in resources to render the arguments

View Source 
var AttributeReferenceTmpl = `` /* 1018-byte string literal not displayed */

AttributeReferenceTmpl contains the definition used in resources to render the attributes

View Source 
var DataSourcesTmpl = fmt.Sprintf(`%s

<h2 id="provider_datasources">Data Sources (using resource id)</h2>
{{if not .DataSourceInstances}}
No data sources using resource id are supported at the moment.
{{- end -}}
{{range .DataSourceInstances -}}
    {{ $datasource := . }}
    <h3 id="{{.Name}}" dir="ltr">{{$.ProviderName}}_{{.Name}}</h3>
	{{if ne .Description "" -}}
	<p>{{.Description}}</p>
	{{else}}
	<p>Retrieve an existing resource using it's ID</p>
	{{- end}}
    <h4 id="datasource_{{.Name}}_example_usage" dir="ltr">Example usage</h4>
<pre><span>data </span><span>"{{$.ProviderName}}_{{$datasource.Name}}" "my_{{$datasource.Name}}"</span>{
    id = "existing_resource_id"
<span>}</span></pre>
    <h4 id="datasource_{{.Name}}_arguments_reference" dir="ltr">Arguments Reference</h4>
    <p dir="ltr">The following arguments are supported:</p>
    <ul dir="ltr">
        <li>id - (Required) ID of the existing resource to retrieve</li>
    </ul>
    <h4 id="datasource_{{.Name}}_attributes_reference" dir="ltr">Attributes Reference</h4>
    <p dir="ltr">In addition to all arguments above, the following attributes are exported:</p>
    {{if $datasource.Properties -}}
        <ul dir="ltr">
            {{- range $datasource.Properties -}}
                {{- template "resource_attribute_reference" . -}}
            {{- end}}
        </ul>
    {{- end}}
{{- $object_property_name := "" -}}
{{- range $datasource.Properties -}}
    {{- if (eq .Type "object")}}
        {{ $object_property_name = .Name }}
    {{end}}
{{- end -}}
{{- if ne $object_property_name "" -}}
    <p><span class="wysiwyg-color-red">* </span>Note: Object type properties are internally represented (in the state file) as a list of one elem due to <a href="https://github.com/hashicorp/terraform-plugin-sdk/issues/155#issuecomment-489699737" target="_blank">Terraform SDK's limitation for supporting complex object types</a>. Please index on the first elem of the array to reference the object values (eg: {{$.ProviderName}}_{{.Name}}.my_{{.Name}}.<b>{{$object_property_name}}[0]</b>.object_property)</p>
{{- end -}}
{{end}} {{/* END range .DataSourceInstances */}}

<h2 id="provider_datasources_filters">Data Sources (using filters)</h2>
{{if not .DataSources}}
No data sources using filters are supported at the moment.
{{- end -}}
{{range .DataSources -}}
    {{ $datasource := . }}
	<h3 id="{{.Name}}_datasource" dir="ltr">{{$.ProviderName}}_{{.Name}} (filters)</h3>
	{{if ne .Description "" -}}
	<p>{{.Description}}</p>
	{{else}}
	<p>The {{.Name}} data source allows you to retrieve an already existing {{.Name}} resource using filters. Refer to the arguments section to learn more about how to configure the filters.</p>
	{{- end}}
    <h4 id="datasource_{{.Name}}_example_usage" dir="ltr">Example usage</h4>
    <pre>
<span>data </span><span>"{{$.ProviderName}}_{{$datasource.Name}}" "my_{{$datasource.Name}}"</span>{
    <span>filter  </span><span>{</span>
        <span>name  </span>= <span>"property name to filter by, see docs below for more info about available filter name options"</span>
        <span>values  </span>= <span>["filter value"]</span>
    <span>}</span>
<span>}</span></pre>

    <h4 id="datasource_{{.Name}}_arguments_reference" dir="ltr">Arguments Reference</h4>
    <p dir="ltr">The following arguments are supported:</p>
    {{if $datasource.Properties -}}
        <ul dir="ltr">
            <li>filter - (Required) Object containing two properties.</li>
            <ul>
                <li>name [string]: the name should match one of the properties to filter by. The following property names are supported:
                {{range $datasource.Properties}}
                    {{if or (eq .Type "string") (eq .Type "integer") (eq .Type "number") (eq .Type "boolean")}}
                        <span>{{.Name}}, </span>
                    {{end}}
                {{end}}
                </li>
                <li>values [array of string]: Values to filter by (only one value is supported at the moment).</li>
            </ul>
        </ul>
    {{- end}}
    <p dir="ltr"><b>Note: </b>If more or less than a single match is returned by the search, Terraform will fail. Ensure that your search is specific enough to return a single result only.</p>
    <h4 id="datasource_{{.Name}}_attributes_reference" dir="ltr">Attributes Reference</h4>
    <p dir="ltr">In addition to all arguments above, the following attributes are exported:</p>
    {{if $datasource.Properties -}}
        <ul dir="ltr">
            {{- range $datasource.Properties -}}
                {{if .Computed -}}
                    {{- template "resource_attribute_reference" . -}}
                {{- end}}
            {{- end}}
        </ul>
    {{- end}}
{{- $object_property_name := "" -}}
{{- range $datasource.Properties -}}
    {{- if (eq .Type "object")}}
        {{ $object_property_name = .Name }}
    {{end}}
{{- end -}}
{{- if ne $object_property_name ""}}
    <p><span class="wysiwyg-color-red">* </span>Note: Object type properties are internally represented (in the state file) as a list of one elem due to <a href="https://github.com/hashicorp/terraform-plugin-sdk/issues/155#issuecomment-489699737" target="_blank">Terraform SDK's limitation for supporting complex object types</a>. Please index on the first elem of the array to reference the object values (eg: {{$.ProviderName}}_{{.Name}}.my_{{.Name}}.<b>{{$object_property_name}}[0]</b>.object_property)</p>
{{- end -}}
{{end}} {{/* END range .DataSources */}}`, AttributeReferenceTmpl)

DataSourcesTmpl contains the template used to render the TerraformProviderDocumentation.DataSources struct as HTML formatted for Zendesk

View Source 
var ProviderConfigurationTmpl = `` /* 1792-byte string literal not displayed */

ProviderConfigurationTmpl contains the template used to render the TerraformProviderDocumentation.ProviderConfiguration struct as HTML formatted for Zendesk

View Source 
var ProviderInstallationTmpl = `` /* 469-byte string literal not displayed */

ProviderInstallationTmpl contains the template used to render the TerraformProviderDocumentation.ProviderInstallation struct as HTML formatted for Zendesk

View Source 
var ProviderResourcesTmpl = fmt.Sprintf(`{{define "resource_example"}}
{{- if .Required}}
    {{if eq .Type "string" -}}
        <span>{{.Name}}  </span>= <span>"{{.Name}}"</span>
    {{- else if eq .Type "integer" -}}
        <span>{{.Name}}  </span>= <span>1234</span>
    {{- else if eq .Type "boolean" -}}
        <span>{{.Name}}  </span>= <span>true</span>
    {{- else if eq .Type "number" -}}
        <span>{{.Name}}  </span>= <span>12.95</span>
    {{- else if and (eq .Type "list") (eq .ArrayItemsType "string") -}}
        <span>{{.Name}}  </span>= <span>["{{.Name}}1", "{{.Name}}2"]</span>
    {{- else if and (eq .Type "list") (eq .ArrayItemsType "integer") -}}
        <span>{{.Name}}  </span>= <span>[1234, 4567]</span>
    {{- else if and (eq .Type "list") (eq .ArrayItemsType "boolean") -}}
        <span>{{.Name}}  </span>= <span>[true, false]</span>
    {{- else if and (eq .Type "list") (eq .ArrayItemsType "number") -}}
        <span>{{.Name}}  </span>= <span>[12.36, 99.45]</span>
    {{- else -}}
        {{- if or (eq .Type "object") (and (eq .Type "list") (eq .ArrayItemsType "object")) -}}
        <span>{{.Name}}  </span><span>{</span>
            {{- range .Schema}}
                {{template "resource_example" .}}
            {{- end}}
            <span>}</span>
        {{- end -}}
    {{- end -}}
{{- end -}}
{{end}}

%s

%s

<h2 id="provider_resources">Provider Resources</h2>
	{{if not .Resources}}
<p>No resources are supported at the moment.</p>
	{{- end -}}
{{range .Resources -}}
	{{ $resource := . }}
<h3 id="{{.Name}}" dir="ltr">{{$.ProviderName}}_{{.Name}}</h3>
{{if ne .Description "" -}}
<p>{{.Description}}</p>
{{- end}}
{{- if .KnownIssues}}
<p>If you experience any issues using this resource, please check the <a href="#resource_{{.Name}}_known_issues" target="_self">Known Issues</a> section to see if there is a fix/workaround.</p>
{{end -}}
<h4 id="resource_{{.Name}}_example_usage" dir="ltr">Example usage</h4>
	{{- if .ExampleUsage}}
		{{- range .ExampleUsage}}
			{{- if .Title}}
<p>{{.Title}}</p>
			{{- end}}
<pre>
{{- .Example}}
</pre>
		{{- end}}
	{{- else}}
<pre>
<span>resource </span><span>"{{$.ProviderName}}_{{$resource.Name}}" "my_{{$resource.Name}}"</span>{
{{- range $resource.Properties -}}
    {{template "resource_example" .}}
{{- end}}
<span>}</span>
</pre>
{{- end}}
<h4 id="resource_{{.Name}}_arguments_reference" dir="ltr">Arguments Reference</h4>
<p dir="ltr">The following arguments are supported:</p>
{{if $resource.Properties -}}
    <ul dir="ltr">
        {{- range $resource.Properties -}}
            {{- template "resource_argument_reference" . -}}
        {{- end}}
    </ul>
{{- end}}
{{- $object_property_name := "" -}}
{{- range $resource.Properties -}}
    {{- if (eq .Type "object")}}
        {{ $object_property_name = .Name }}
    {{end}}
{{- end -}}
{{- if ne $object_property_name "" -}}
    <p><span class="wysiwyg-color-red">* </span>Note: Object type properties are internally represented (in the state file) as a list of one elem due to <a href="https://github.com/hashicorp/terraform-plugin-sdk/issues/155#issuecomment-489699737" target="_blank">Terraform SDK's limitation for supporting complex object types</a>. Please index on the first elem of the array to reference the object values (eg: {{$.ProviderName}}_{{.Name}}.my_{{.Name}}.<b>{{$object_property_name}}[0]</b>.object_property)</p>
{{- end -}}
{{range .ArgumentsReference.Notes}}
    <p><span class="wysiwyg-color-red">*Note: {{.}}</span></p>
{{end}}

<h4 id="resource_{{.Name}}_attributes_reference" dir="ltr">Attributes Reference</h4>
<p dir="ltr">In addition to all arguments above, the following attributes are exported:</p>
{{if $resource.Properties -}}
    <ul dir="ltr">
        {{- range $resource.Properties -}}
            {{- template "resource_attribute_reference" . -}}
        {{- end}}
    </ul>
{{- end -}}
{{- $object_property_name := "" -}}
{{- range $resource.Properties -}}
    {{- if (eq .Type "object")}}
        {{ $object_property_name = .Name }}
    {{end}}
{{- end -}}
{{- if ne $object_property_name "" -}}
    <p><span class="wysiwyg-color-red">* </span>Note: Object type properties are internally represented (in the state file) as a list of one elem due to <a href="https://github.com/hashicorp/terraform-plugin-sdk/issues/155#issuecomment-489699737" target="_blank">Terraform SDK's limitation for supporting complex object types</a>. Please index on the first elem of the array to reference the object values (eg: {{$.ProviderName}}_{{.Name}}.my_{{.Name}}.<b>{{$object_property_name}}[0]</b>.object_property)</p>
{{- end -}}

<h4 id="resource_{{.Name}}_import" dir="ltr">Import</h4>
<p dir="ltr">
    {{.Name}} resources can be imported using the&nbsp;<code>id</code> {{if ne $resource.BuildImportIDsExample "id"}}. This is a sub-resource so the parent resource IDs (<code>{{$resource.ParentProperties}}</code>) are required to be able to retrieve an instance of this resource{{end}}, e.g:
</p>
<pre dir="ltr">$ terraform import {{$.ProviderName}}_{{.Name}}.my_{{.Name}} {{$resource.BuildImportIDsExample}}</pre>
<p dir="ltr">
    <strong>Note</strong>: In order for the import to work, the '{{$.ProviderName}}' terraform
    provider must be&nbsp;<a href="#provider_installation" target="_self">properly installed</a>. Read more about Terraform import usage&nbsp;<a href="https://www.terraform.io/docs/import/usage.html" target="_blank" rel="noopener noreferrer">here</a>.
</p>
	{{if .KnownIssues}}
<h4 id="resource_{{.Name}}_known_issues" dir="ltr">Known Issues</h4>
		{{range .KnownIssues}}
<p><i>{{.Title}}</i></p>
<p>{{.Description}}</p>
			{{- range .Examples}}
				{{- if .Title}}
<p>{{.Title}}</p>
				{{- end}}
<pre>{{.Example}}</pre>
			{{- end}}
		{{end}}
	{{- end}}
{{end}} {{/* END range .Resources */}}`, ArgumentReferenceTmpl, AttributeReferenceTmpl)

ProviderResourcesTmpl contains the template used to render the TerraformProviderDocumentation.ProviderResources struct as HTML formatted for Zendesk

View Source 
var SpecialTermsTmpl = `` /* 1598-byte string literal not displayed */

SpecialTermsTmpl contains the template used to render the special terms definitions section as HTML formatted for Zendesk

View Source 
var TableOfContentsTmpl = `` /* 2235-byte string literal not displayed */

TableOfContentsTmpl contains the template used to render the table of contents as HTML formatted for Zendesk

Functions

This section is empty.

Types

type ArgumentsReference 

type ArgumentsReference struct {
	Notes []string
}

ArgumentsReference defines any notes that need to be appended to a resource's arguments reference section (eg: known issues)

type AttributesReference 

type AttributesReference struct {
	Description string
	Properties  []Property
	Notes       []string
}

AttributesReference defines the attributes needed for a resource's attributes reference section

type DataSource 

type DataSource struct {
	Name         string
	Description  string
	OtherExample string
	Properties   []Property
}

DataSource defines the attributes to generate documentation for a Terraform provider data source

type DataSources 

type DataSources struct {
	// ProviderName is the name of the provider
	ProviderName        string
	DataSources         []DataSource
	DataSourceInstances []DataSource
}

DataSources defines the data sources and data source instances exposed by the Terraform provider

type ExampleUsage 

type ExampleUsage struct {
	Title   string
	Example string
}

ExampleUsage defines a block of code/commands to include in the docs

type KnownIssue added in v0.30.1 

type KnownIssue struct {
	Title       string
	Description string
	Examples    []ExampleUsage
}

KnownIssue defines any known issues associated with a resource

type Property 

type Property struct {
	Name               string
	Type               string
	ArrayItemsType     string
	Required           bool
	Computed           bool
	IsOptionalComputed bool
	IsSensitive        bool
	Description        string
	Schema             []Property // This is used to describe the schema for array of objects or object properties
}

Property defines the attributes for describing a given property for a resource

func (Property) ContainsComputedSubProperties 

func (p Property) ContainsComputedSubProperties() bool

ContainsComputedSubProperties checks if a schema contains properties that are computed recursively

type ProviderConfiguration 

type ProviderConfiguration struct {
	// ProviderName is the name of the provider
	ProviderName       string
	Regions            []string
	ConfigProperties   []Property
	ExampleUsage       []ExampleUsage
	ArgumentsReference ArgumentsReference
}

ProviderConfiguration defines the details needed to properly configure the Terraform provider

type ProviderInstallation 

type ProviderInstallation struct {
	// ProviderName is the name of the provider
	ProviderName string
	// Example code/commands for installing the provider
	Example string
	// Other instructions to install/run the provider
	Other string
	// Other code/commands needed to install/run the provider
	OtherCommand string
}

ProviderInstallation includes details needed to install the Terraform provider plugin

type ProviderResources 

type ProviderResources struct {
	// ProviderName is the name of the provider
	ProviderName string
	Resources    []Resource
}

ProviderResources defines the resources exposed by the Terraform provider

func (ProviderResources) ContainsResourcesWithSecretProperties 

func (r ProviderResources) ContainsResourcesWithSecretProperties() bool

ContainsResourcesWithSecretProperties checks if the provider exposes resources containing secret properties

type Resource 

type Resource struct {
	Name               string
	Description        string
	Properties         []Property
	ParentProperties   []string
	ExampleUsage       []ExampleUsage
	ArgumentsReference ArgumentsReference
	KnownIssues        []KnownIssue
}

Resource defines the attributes to generate documentation for a Terraform provider resource

func (Resource) BuildImportIDsExample 

func (r Resource) BuildImportIDsExample() string

BuildImportIDsExample creates a string containing the import id hierarchy in case the resource is a sub-resource

type TerraformProviderDocGenerator 

type TerraformProviderDocGenerator struct {
	// ProviderName defines the provider name
	ProviderName string
	// SpecAnalyser analyses the swagger doc and provides helper methods to retrieve all the end points that can
	// be used as terraform resources.
	SpecAnalyser openapi.SpecAnalyser
}

TerraformProviderDocGenerator defines the struct that holds the configuration needed to be able to generate the documentation

func NewTerraformProviderDocGenerator 

func NewTerraformProviderDocGenerator(providerName, openAPIDocURL string) (TerraformProviderDocGenerator, error)

NewTerraformProviderDocGenerator returns a TerraformProviderDocGenerator populated with the provider documentation which exposes methods to render the documentation in different formats (only html supported at the moment)

func (TerraformProviderDocGenerator) GenerateDocumentation 

func (t TerraformProviderDocGenerator) GenerateDocumentation() (TerraformProviderDocumentation, error)

GenerateDocumentation creates a TerraformProviderDocumentation object populated based on the OpenAPIDocURL documentation

type TerraformProviderDocumentation 

type TerraformProviderDocumentation struct {
	ProviderName                string
	ProviderNotes               []string
	ProviderInstallation        ProviderInstallation
	ProviderConfiguration       ProviderConfiguration
	ProviderResources           ProviderResources
	DataSources                 DataSources
	ShowSpecialTermsDefinitions bool
}

TerraformProviderDocumentation defines the attributes needed to generate Terraform provider documentation

func (TerraformProviderDocumentation) RenderHTML 

func (t TerraformProviderDocumentation) RenderHTML(w io.Writer) error

RenderHTML writes to the given writer argument the Terraform provider documentation

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.