Working with other API specs
OpenAPI Integration
Overview
Taxi can be embedded within OpenAPI specifications to add semantic meaning to APIs. This allows you to:
- Define semantic types for request/response models
- Add semantic meaning to API parameters
- Create a unified semantic layer across multiple APIs
Semantic Enhancement
Adding Taxi to OpenAPI
Basic Syntax
Taxi metadata is added using x-taxi-type extensions in your OpenAPI spec:
x-taxi-type:
name: com.acme.MyType # The semantic type name
create: false # Optional flag to control type creationType Creation Behavior
The create flag controls whether new types are created if they don’t exist.
The default behaviour varies between models and field attributes - and defaults to the reccomended best practice for each.
| Context | Default | Behavior |
|---|---|---|
| Response Models | true | Creates new types if not found |
| Field Attributes | false | Requires types to exist |
Type Creation
Semantic types let you share data between systems, while avoiding tight coupling. Try to use existing types (where the semantics match), or create new types in a shared taxonomy - rather than creating types in your OpenAPI spec
Only create new types (create: true) when you're intentionally extending your semantic model, or creating a type you're not ready to share yet.
Declaring operation kinds
Some TaxiQL behavior depends on whether operations are read-only or write operations (sometimes referred to as ‘mutations’).
By default:
- GET, HEAD, and OPTIONS methods are treated as read operations (default, no modifier)
- POST, PUT, PATCH, and DELETE methods are treated as write operations
You can override this default behavior using x-taxi-operation-kind at the operation level:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
paths:
/pets:
# POST operations are 'write' by default, but this can be overridden
post:
x-taxi-operation-kind: read # Override to make a POST operation read-only
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
name:
type: string
# GET operations are 'read' by default, but this can be overridden
get:
x-taxi-operation-kind: write # Override to make a GET operation a write operation
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
name:
type: stringPossible values for x-taxi-operation-kind:
read- The operation is read-only (default for GET, HEAD, OPTIONS)write- The operation modifies data (default for POST, PUT, PATCH, DELETE)
Enriching OpenAPI Components
Response Models
Add semantic meaning to response types:
components:
schemas:
Customer:
x-taxi-type:
name: acme.Customer
properties:
id:
type: string
x-taxi-type:
name: acme.CustomerId
email:
type: string
x-taxi-type:
name: acme.EmailAddress
Input Parameters
Enrich API parameters with semantic types:
paths:
/customers/{id}:
get:
parameters:
- name: id
in: path
schema:
type: string
x-taxi-type:
name: acme.CustomerId
Field Attributes
Add semantic meaning to model fields:
components:
schemas:
Customer:
properties:
name:
type: string
x-taxi-type:
name: acme.CustomerName
# Only create if type doesn't exist
create: true