Import: OpenAPI

Creates a data contract from the responses of GET or POST operations in an OpenAPI 3.0 or 3.1 document, in YAML or JSON. You can then test the endpoints against the contract.

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

What is imported

• Operation: select the operation with --operation, by its operationId (listOrders), its method and path (GET /orders, POST /orders/search), or the path of a GET operation (/orders). Repeat --operation to import several operations. In a terminal, --operation can be omitted to pick the operations from a list of those with an importable response. Otherwise, if the document has only one GET operation, --operation can be omitted. A POST operation is never selected by its path alone, because a POST may change data: import only POST operations that read, such as a search.
• Schema: the contract gets one schema per operation, 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. With several operations, the location is the server URL, and each schema has an endpoint custom property with its path, and its own method, params and body. Relative server URLs (such as /v1) are skipped with a warning, because they cannot be tested.
• Parameters: path parameters become variables in the location (with several operations, in the schema's endpoint), and required query parameters variables in the params custom property, 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.
• Request body: for a POST operation, the server (with several operations, the schema) gets method: POST and a body custom property with the request body's JSON example: the media type's example, else its first entry in examples, else the schema's example. Without one, the contract has no body and a warning asks you to add it.

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.