Endpoint and Schema Extensions

These extensions add details to operations, parameters, responses, and schemas.

Add deprecation detailsCopy Anchor Link

When an operation has deprecated: true, x-deprecation-details in its Operation Object adds more about the deprecation. APIMatic ignores the extension on operations that aren't deprecated.

paths:
  /pets:
    post:
      operationId: addPet
      deprecated: true
      x-deprecation-details:
        message: Use createPet instead.
        deprecatedInVersion: "2.0"

Split the request body into parametersCopy Anchor Link

OpenAPI allows one request body per operation. Set x-unwrap-body: true in the Operation Object to import each property of the body schema as a separate body parameter. The request still sends the parameters together as one object.

APIMatic unwraps the body only when its schema is an object with properties.

paths:
  /pets:
    post:
      operationId: addPet
      x-unwrap-body: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewPet"

Rename a parameterCopy Anchor Link

x-unique-name in a Parameter Object (OpenAPI 3.x) gives the parameter a different name in SDKs and docs. The request still uses the original name. Use it to tell apart parameters that share a name, or to replace a long or unclear name.

parameters:
  - name: id
    in: path
    required: true
    schema:
      type: string
    x-unique-name: orderId
  - name: id
    in: query
    schema:
      type: string
    x-unique-name: customerId

Pick a name that no other parameter of the operation uses. The OpenAPI v3 APIMatic Linting rule unique-parameter-name reports parameters whose names clash.

Add a parameter exampleCopy Anchor Link

Swagger 2.0 has no example property for parameters. Set x-example in the Parameter Object instead.

parameters:
  - name: status
    in: query
    type: string
    x-example: available

Describe paginationCopy Anchor Link

x-pagination describes how an endpoint returns its results in pages. Add it to the Media Type Object of the success response, next to schema. It's an array with one entry per pagination strategy the endpoint supports.

A pointer is a runtime expression followed by a JSON pointer:

• Request values: $request.query#/, $request.path#/, $request.headers#/, or $request.body#/, followed by the name, for example $request.query#/offset.
• Response values: $response.body for the whole body, or $response.body#/ or $response.headers#/ followed by a path, for example $response.body#/data.

paths:
  /payments:
    get:
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: A page of payments
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentList"
              x-pagination:
                - type: offset
                  input: $request.query#/offset
                  limit: $request.query#/limit
                  result: $response.body#/data
                  totalItems: $response.body#/total

A cursor strategy reads the next cursor from the response:

x-pagination:
  - type: cursor
    input: $request.query#/cursor
    output: $response.body#/next_cursor
    result: $response.body#/data
    hasMore: $response.body#/has_more

The pagination rules are in the Pagination section of OpenAPI v3 APIMatic Linting. For which SDK languages support pagination, see Languages & Features.

Mark the end of an event streamCopy Anchor Link

Some Server-Sent Events streams end with a frame that carries a fixed value, such as [DONE]. Set x-sse-sentinel in the text/event-stream Media Type Object of the success response to the exact data value of that frame.

responses:
  "200":
    description: A stream of completion chunks
    content:
      text/event-stream:
        schema:
          $ref: "#/components/schemas/CompletionChunk"
        x-sse-sentinel: "[DONE]"

In YAML, quote values that contain characters such as [ and ], so they're read as strings.

Name and describe enum valuesCopy Anchor Link

x-enum-elements gives each value of an enum a name and a description. List one element per enum value, in the same order as enum. If the counts don't match, APIMatic ignores the extension.

components:
  schemas:
    Priority:
      type: integer
      enum: [1, 2, 3]
      x-enum-elements:
        - name: Low
          description: Handle when convenient.
        - name: Medium
          description: Handle today.
        - name: High
          description: Handle now.

In OpenAPI 3.x, add it to the Schema Object. In Swagger 2.0, add it to the Schema Object or to a Parameter Object that has an enum.

Name an enum modelCopy Anchor Link

APIMatic creates a model for each enum. To set the model's name:

• In OpenAPI 3.x, set x-enum-model-name in the Schema Object.
• In Swagger 2.0, set x-enum-model-name in a Parameter Object that has an enum.

parameters:
  - name: status
    in: query
    schema:
      type: string
      enum: [available, pending, sold]
      x-enum-model-name: PetStatus

Set a discriminator valueCopy Anchor Link

By default, the discriminator value of a schema is its name. To use a different value, set x-discriminator-value. In OpenAPI 3.x, add it to the Discriminator Object. In Swagger 2.0, add it to the Schema Object, next to discriminator.

components:
  schemas:
    Pet:
      type: object
      required: [petType]
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        x-discriminator-value: GenericPet

Mark a schema as dynamicCopy Anchor Link

When a schema's shape isn't known or can't be described, set x-is-dynamic: true in its Schema Object. APIMatic imports it as a dynamic type instead of a typed model.

responses:
  "200":
    description: Any JSON value
    content:
      application/json:
        schema:
          type: object
          x-is-dynamic: true

Name an error modelCopy Anchor Link

APIMatic creates an error model from each schema that an error response uses. By default, the model is named after the schema, with an _Error suffix. To use a different name, set x-exception-model-name in the Schema Object.

components:
  schemas:
    BadRequest:
      type: object
      x-exception-model-name: ValidationError
      properties:
        message:
          type: string

Date-time formatsCopy Anchor Link

OpenAPI's date-time format means RFC 3339. APIMatic reads two more values of the standard format property as date-time types:

properties:
  createdAt:
    type: number
    format: unix-timestamp