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 creation
Type 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: string
Possible 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