Workflow to generate an OpenAPI Doc from a data values schema

commands.md

1. Run this command to use a data value and schema file together. You can see if you change a value in the values.yml to be the incorrect type, you will see an error catches this. ytt -f /values.yml -f schema.yml -f template.yml

2. Generate the OpenAPI schema from the schema.yml file. ytt -f schema.yml --data-values-schema-inspect -o openapi-v3 > openapi-schema.yml

3. You can use this OpenAPI schema as documentation, or use it in a a kapp-controller Custom Resource, to document what inputs are allowed in the package. ytt -f package-template.yml --data-value-file openapi=openapi-schema.yml > package.yml

package-template.yml

#@ load("@ytt:data", "data")
#@ load("@ytt:yaml", "yaml")
---
apiVersion: data.packaging.carvel.dev/v1alpha1
kind: Package
metadata:
  name: example.carvel.dev.1.5.3
  namespace: my-ns
spec:
  valuesSchema:
    openAPIv3:  #@ yaml.decode(data.values.openapi)["components"]["schemas"]["dataValues"]
  refName: example.carvel.dev
  version: 1.5.3
  releaseNotes: "Fixed some bugs"
  template:
    spec:
      fetch:
        - imgpkgBundle:
            image: registry.tkg.vmware.run/example@sha256:...
      template:
        - ytt:
            paths:
              - config/
        - kbld:
            paths:
              - .imgpkg/images.yml
      deploy:
        - kapp: { }

schema.yml

#! schema.yml

#@data/values-schema
---
#@schema/desc "Whether to include a LoadBalancer type service and if so, what its IP address is."
load_balancer:
  enabled: true
  #@schema/nullable
  static_ip: ""

#@schema/desc "DNS domains to accept traffic for."
#@schema/default ["apps.example.com", "mobile.example.com"]
app_domains:
  - ""

#@schema/desc "Connection information for databases used by the system."
databases:
  - name: ""
    #@schema/desc "postgres or mysql2, as needed"
    adapter: postgresql
    host: ""
    port: 5432

#@schema/desc "Configuration for experimental/optional components"
#@schema/type any=True
additional_config: { }

template.yml

#@ load("@ytt:data", "data")
---
data_values: #@ data.values

values.yml

#! values.yml

#@data/values
---
#! Whether to include a LoadBalancer type service and if so, what its IP address is.
load_balancer:
  enabled: false
  static_ip: null

#! DNS domains to accept traffic for
app_domains:
  - "additional.domain.dev"

#! Connection information for databases used by the system
databases:
  - name: "postgres"
    #! postgres or mysql2, as needed
    adapter: postgresql
    host: ""
    port: 5432