Skip to main content

Import: OpenAPI

Creates a data contract from the response of one GET operation in an OpenAPI 3.0 or 3.1 document, in YAML or JSON. You can then test the endpoint against the contract.

datacontract import openapi --source openapi.yaml --operation listOrders

What is imported​

  • Operation: select the GET operation with --operation, by its operationId (listOrders) or its path (/orders). If the document has only one GET operation, --operation can be omitted.
  • Schema: the contract gets one schema, named after the operationId (or the path), described by the operation's summary or description. Its properties come from the response schema of the first success response (200 first, then other 2xx codes) with a JSON (application/json, application/*+json) or YAML (application/yaml, text/yaml) body.
  • Arrays: if the response is an array, the schema describes its items, which are the records.
  • Types: the response schema is mapped like a JSON Schema. Local $refs (to #/components/...) are resolved and allOf is merged. OpenAPI 3.0's example is imported as examples. A property that admits null (nullable: true, or type: [string, "null"]) is not required, as ODCS required means not null.
  • Servers: every absolute servers URL becomes an api server whose location is the endpoint's URL. Server variables take their default. Relative server URLs (such as /v1) are skipped with a warning, because they cannot be tested.
  • Parameters: path parameters and required query parameters become variables in the location, defaulting to the parameter's example or default. For example, /orders/{orderId} with example: ORD-1001 becomes /orders/${orderId:-ORD-1001}. Set orderId in the environment to test another order.

Swagger 2.0 documents are not supported, and $refs to other files are not followed.

Example​

Given this orders.yaml:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging.api.example.com/v1
    description: Staging
paths:
  /orders:
    get:
      operationId: listOrders
      summary: All orders of the last 30 days.
      responses:
        "200":
          description: The orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          example: ORD-1001
          schema:
            type: string
      responses:
        "200":
          description: The order.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
components:
  schemas:
    Order:
      type: object
      required: [order_id, order_timestamp, status]
      properties:
        order_id:
          type: string
          description: Unique identifier of the order.
          pattern: "^ORD-[0-9]+$"
        order_timestamp:
          type: string
          format: date-time
        customer_id:
          type: string
        order_total:
          type: integer
          minimum: 0
        status:
          type: string
          enum: [placed, shipped, delivered]

Run:

datacontract import openapi --source orders.yaml --operation listOrders

to produce the data contract:

version: 1.0.0
kind: DataContract
apiVersion: v3.2.0
id: my-data-contract
name: Orders API
status: draft
servers:
- server: production
  type: api
  description: Production
  location: https://api.example.com/v1/orders
- server: staging
  type: api
  description: Staging
  location: https://staging.api.example.com/v1/orders
schema:
- name: listOrders
  physicalType: object
  description: All orders of the last 30 days.
  logicalType: object
  physicalName: listOrders
  properties:
  - name: order_id
    physicalType: string
    description: Unique identifier of the order.
    logicalType: string
    logicalTypeOptions:
      pattern: ^ORD-[0-9]+$
    required: true
  - name: order_timestamp
    physicalType: string
    logicalType: string
    logicalTypeOptions:
      format: date-time
# …

All options: datacontract import openapi.