Configure OpenAPI → Terraform Binding

Brandon Croft,•apiterraform

After experimenting with a YAML configuration file to generate and store binding information, it felt like the depth of parameter configuration required was tedious and confusing.

Another way to configure the code generator tool is to use OpenAPI Extension properties, which are extra properties usually beginning with "x-", on the following OpenAPI schema:

Here are some potential extensions needed to fully generate Terraform Provider schema:

Resource binding

Paths and operations are bound to a single Terraform resources' create/read/delete/update methods.

Option #1 is to bind these together as a named resource using implied REST method mapping:

paths:
  /quotas:
    get:
      responses:
        '200':
          description: OK
  /quotas/{id}:
    post:
      X-Terraform-Resource: "nomad_quota"
      responses:
        '201':
          description: OK
    delete:
      X-Terraform-Resource: "nomad_quota"
      responses:
        '201':
          description: OK
    get:
      X-Terraform-Resource: "nomad_quota"
      responses:
        '200':
          description: OK
    ...

Option #2 is to be fully flexible on each path:

paths:
  /quota:
    X-Terraform-Resource:
      name: quota
    post:
      X-Terraform-Resource-Action: Create
      operationId: CreateQuotaSpec
      parameters:
      - $ref: '#/components/parameters/RegionParam'
      - $ref: '#/components/parameters/NamespaceParam'
      - $ref: '#/components/parameters/NomadTokenHeader'
      - $ref: '#/components/parameters/IdempotencyTokenParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotaSpec'
        required: true
      responses:
        "200":
          $ref: '#/components/responses/CreateQuotaSpecResponse'
        "400":
          $ref: '#/components/responses/BadRequestResponse'
        "403":
          $ref: '#/components/responses/ForbiddenResponse'
        "405":
          $ref: '#/components/responses/MethodNotAllowedResponse'
        "500":
          $ref: '#/components/responses/InternalServerErrorResponse'
      security:
      - X-Nomad-Token: []
      tags:
      - Enterprise
  /quota/{specName}:
    delete:
      X-Terraform-Resource-Action: Delete
      operationId: DeleteQuotaSpec
      parameters:
      - $ref: '#/components/parameters/RegionParam'
      - $ref: '#/components/parameters/NamespaceParam'
      - $ref: '#/components/parameters/NomadTokenHeader'
      - $ref: '#/components/parameters/IdempotencyTokenParam'
      - $ref: '#/components/parameters/QuotaSpecNameParam'
      responses:
        "200":
          $ref: '#/components/responses/DeleteNamespaceResponse'
        "400":
          $ref: '#/components/responses/BadRequestResponse'
        "403":
          $ref: '#/components/responses/ForbiddenResponse'
        "405":
          $ref: '#/components/responses/MethodNotAllowedResponse'
        "500":
          $ref: '#/components/responses/InternalServerErrorResponse'
      security:
      - X-Nomad-Token: []
      tags:
      - Enterprise
    get:
      operationId: GetQuotaSpec
      parameters:
      - $ref: '#/components/parameters/RegionParam'
      - $ref: '#/components/parameters/NamespaceParam'
      - $ref: '#/components/parameters/IndexHeader'
      - $ref: '#/components/parameters/WaitParam'
      - $ref: '#/components/parameters/StaleParam'
      - $ref: '#/components/parameters/PrefixParam'
      - $ref: '#/components/parameters/NomadTokenHeader'
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/NextTokenParam'
      - $ref: '#/components/parameters/QuotaSpecNameParam'
      responses:
        "200":
          $ref: '#/components/responses/GetQuotaSpecResponse'
        "400":
          $ref: '#/components/responses/BadRequestResponse'
        "403":
          $ref: '#/components/responses/ForbiddenResponse'
        "405":
          $ref: '#/components/responses/MethodNotAllowedResponse'
        "500":
          $ref: '#/components/responses/InternalServerErrorResponse'
      security:
      - X-Nomad-Token: []
      tags:
      - Enterprise
    post:
      operationId: PostQuotaSpec
      parameters:
      - $ref: '#/components/parameters/RegionParam'
      - $ref: '#/components/parameters/NamespaceParam'
      - $ref: '#/components/parameters/NomadTokenHeader'
      - $ref: '#/components/parameters/IdempotencyTokenParam'
      - $ref: '#/components/parameters/QuotaSpecNameParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotaSpec'
        required: true
      responses:
        "200":
          $ref: '#/components/responses/PostQuotaSpecResponse'
        "400":
          $ref: '#/components/responses/BadRequestResponse'
        "403":
          $ref: '#/components/responses/ForbiddenResponse'
        "405":
          $ref: '#/components/responses/MethodNotAllowedResponse'
        "500":
          $ref: '#/components/responses/InternalServerErrorResponse'
      security:
      - X-Nomad-Token: []
      tags:
      - Enterprise
© Brandon Croft.