Tigrister Extensions

Custom OpenAPI Extensions

Tigrister uses vendor extensions (x-tigrister-*) to store application-specific data in your OpenAPI spec. These extensions enable features like test assertions, auth configurations, and project metadata.

Key Concepts
  • • OpenAPI Compliant - All x-* extensions are valid per spec
  • • Round-Trip Safe - Extensions survive import/export cycles
  • • Optional Cleanup - Export clean specs without extensions
  • • Sync Aware - Preserved during bi-directional sync

Available Extensions

Tigrister defines the following vendor extensions:

ExtensionLocationPurpose
x-tigrister-assertionsOperationTest assertions for responses
x-tigrister-authOperationPer-endpoint auth configuration
x-tigrister-enabledOperationEnable/disable endpoint in tests
x-tigrister-env-idServerStable environment identifier
x-tigrister-env-nameServerCustom environment display name
x-tigrister-project-idRoot (info)Project tracking ID
x-tigrister-versionRoot (info)Tigrister format version
x-tigrister-module-idTagModule/folder identifier
x-tigrister-endpoint-idOperationEndpoint tracking ID

x-tigrister-assertions

Testing

Define test assertions that run automatically when you send a request. Assertions verify response status, headers, body content, and more.

Full Example
paths:
/users/{id}:
get:
summary: Get user by ID
x-tigrister-assertions:
# Status code check
- type: status
operator: equals
expected: 200
# Response time check
- type: response_time
operator: less_than
expected: 500
# Header check
- type: header
property: Content-Type
operator: contains
expected: application/json
# JSON path exists check
- type: json_path
property: $.id
operator: exists
# JSON path value check
- type: json_path
property: $.status
operator: equals
expected: active
# Body contains check
- type: body
operator: contains
expected: "success"

Assertion Types

  • status - HTTP status code
  • response_time - Response time in ms
  • header - Header value check
  • json_path - JSON path validation
  • body - Raw body content

Comparison Operators

  • equals / not_equals
  • contains / not_contains
  • exists / not_exists
  • greater_than / less_than
  • is_empty / is_not_empty
  • matches_regex / is_type

x-tigrister-auth

Auth

Override the authentication method for specific operations. Useful when an endpoint needs different auth than the global security setting.

Bearer Token Override
/admin/settings:
get:
x-tigrister-auth:
type: bearer
token: admin-token-here
API Key Override
/webhooks:
post:
x-tigrister-auth:
type: apiKey
name: X-Webhook-Secret
in: header
value: secret123
Basic Auth Override
/legacy/endpoint:
get:
x-tigrister-auth:
type: basic
username: admin
password: pass123
No Auth (Public)
/public/health:
get:
x-tigrister-auth:
type: none

Security Note

Auth credentials in x-tigrister-auth are stored in your spec file. Use environment variables or exclude this extension when sharing specs externally.

x-tigrister-enabled

Testing

Enable or disable operations in test runs. Useful for temporarily skipping broken or incomplete endpoints.

paths:
/users:
get:
summary: List users
x-tigrister-enabled: true
delete:
summary: Delete all users
# Disabled - dangerous operation
x-tigrister-enabled: false

enabled: true (default)

Operation runs in test suites and appears in Area Mode.

enabled: false

Operation is skipped in automated tests. Still visible in UI.

Environment Extensions

Server

Control how servers map to Tigrister environments with stable IDs and custom display names.

x-tigrister-env-id & x-tigrister-env-name
servers:
- url: https://api.example.com
description: Production server
x-tigrister-env-id: prod-env-001
x-tigrister-env-name: Production
- url: https://staging.example.com
description: Staging server for testing
x-tigrister-env-id: staging-env-002
x-tigrister-env-name: Staging
- url: http://localhost:3000
x-tigrister-env-id: local-dev
x-tigrister-env-name: Local Dev

x-tigrister-env-id

Stable identifier for the environment. Preserves selection across re-imports even if URL or description changes.

x-tigrister-env-name

Display name in the UI. Takes precedence over the server'sdescription field.

Project Metadata

Tracking

Internal tracking extensions added by Tigrister for project management. Generally you don't need to edit these manually.

info:
title: My API
version: '1.0.0'
x-tigrister-project-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
x-tigrister-version: '1.0'
tags:
- name: Users
x-tigrister-module-id: users-module-001
paths:
/users:
get:
operationId: listUsers
x-tigrister-endpoint-id: endpoint-xyz-789

Auto-Generated IDs

Project, module, and endpoint IDs are generated automatically by Tigrister. They enable stable sync between spec and project even when names change.

Clean Export (Removing Extensions)

When exporting your spec for external use, you can remove all Tigrister extensions to get a standard, portable OpenAPI document.

With Extensions

Includes all x-tigrister-* fields. Use for Tigrister backups or sharing with other Tigrister users.

  • + Test assertions preserved
  • + Auth configs included
  • + Environment IDs stable
Clean Export

Removes all x-tigrister-* fields. Use for code generation, documentation, or sharing externally.

  • + Standard OpenAPI
  • + No sensitive data
  • + Tool compatible

How to Clean Export

In the Export panel, toggle "Remove Tigrister Extensions" before downloading. This strips all x-tigrister-* fields from the output.

Round-Trip Fidelity

Tigrister preserves your extensions through the import → edit → export cycle:

Import Spec
Edit in Tigrister
Export Spec

Extensions you didn't touch remain exactly as imported. Tigrister only modifies sections you actually edit.

Preservation Guarantee

Unknown vendor extensions (x-*) from other tools are also preserved. Tigrister only manages its own x-tigrister-* namespace.

Related Topics
→ Area Mode→ Authentication→ Export→ Bi-Directional Sync
TroubleshootingBest Practices