Visual Designer

Form-Based Editing

The Visual Designer provides a form-based interface to edit every part of your OpenAPI spec. No YAML or JSON knowledge required - changes are automatically converted to the spec format.

State Persistence

The Visual Designer remembers your view state per project:

Expanded Sections

Which sections are open

Scroll Position

Jump back to where you were

Expanded Paths

Which paths are expanded

Default State

When opening a project for the first time, the Info and Paths sections are expanded by default.

Empty & Error States

The Visual Designer shows helpful messages when the spec isn't ready:

Empty State

Shown when there's no valid OpenAPI spec. Prompts you to edit the code or paste a valid spec in the Code Editor.

Error State

Shown when the spec has validation errors. Lists the errors and hides the visual editor until you fix them in the Code Editor.

Collapsible Sections

The Visual Designer organizes the spec into collapsible sections:

Info Section

Edit your API's basic information:

TitleAPI name displayed in docs
DescriptionMarkdown-supported description
VersionAPI version (e.g., 1.0.0)
ContactName, email, URL (read-only)
LicenseLicense name and URL (read-only)

Servers Section

Define base URLs for your API. Supports server variables for dynamic parts.

https://api.example.com/v1Production

No variables defined

https://{environment}.api.example.comDynamic
Variables: environment (staging, prod)

Tags (Modules) Section

Tags in OpenAPI become Modules in Tigrister. They group related endpoints together.

Users
Orders

Edit and delete icons appear on hover. Descriptions are shown below the pills when defined.

Paths (Endpoints) Section

Operations are grouped by tag (module). Expand a tag to see its operations, then expand an operation to edit its details.

Users
4 operation(s)
get/usersList all users
post/usersCreate a new user
get/users/{userId}Get user by ID
delete/users/{userId}Delete user
Orders
3 operation(s)

Operation Details

Click on any operation to expand it. The expanded view lets you edit all operation details:

Summary & Description

Operation metadata

Operation ID

Unique identifier

Parameters

Path, query, header params

Request Body

Schema and content types

Responses

Status codes and schemas

Callbacks

Async notifications

Schemas (Models) Section

Define reusable data models for requests and responses. Full support for JSON Schema.

Supported Types
stringnumberintegerbooleanarrayobject
Features
  • • $ref references to other schemas
  • • allOf / oneOf / anyOf composition
  • • Enum values
  • • Min/max constraints
  • • Pattern validation (regex)
  • • Format hints (email, date, uuid, etc.)

Usage Tracking

Each schema shows a usage badge indicating how many operations reference it. Schemas with no references are marked as "unused", helping you identify dead models.

Schema Composition in Visual Designer

Create complex schemas using composition keywords directly in the Visual Designer:

allOfInheritance / Extend

Combine multiple schemas. The result must satisfy ALL schemas (like interface extension).

BaseEntity
+
UserFields
=
User

User has all properties from both BaseEntity and UserFields.

oneOfPolymorphism / Exactly One

Value must match exactly ONE of the schemas (like union types with discriminator).

Pet
=
Cat
|
Dog
|
Bird

A Pet is either a Cat, Dog, or Bird - never multiple. Use with discriminator.

anyOfFlexible Union / One or More

Value must match AT LEAST ONE schema (more flexible than oneOf).

PaymentID
=
string
|
integer

PaymentID can be either a string or integer (useful for flexible inputs).

Adding Composition in Visual Designer
  1. Open a schema in the Visual Designer
  2. Click "Add Composition" button
  3. Choose allOf, oneOf, or anyOf
  4. Select existing schemas to combine, or create inline schemas
  5. For oneOf, optionally set a discriminator property

Security Schemes Section

Define authentication methods for your API:

API Key

Authentication via header, query, or cookie.

type: apiKey
in: header
name: X-API-Key
HTTP Auth

Basic auth, Bearer token, etc.

type: http
scheme: bearer
bearerFormat: JWT
OAuth 2.0

Full OAuth 2.0 flows with scopes.

type: oauth2
flows: authorizationCode,
  clientCredentials, ...
OpenID Connect

Discover auth endpoints from URL.

type: openIdConnect
openIdConnectUrl:
  https://.../.well-known/...

Security Scheme Setup Walkthrough

Follow these steps to set up authentication for your API in the Visual Designer:

1

Open Security Schemes Section

Click on "Security Schemes" in the Visual Designer sidebar to expand the section.

2

Add New Security Scheme

Click "+ Add Security Scheme" and choose the authentication type:

API Key - Header, query, or cookie key
HTTP - Basic or Bearer token
OAuth 2.0 - Full OAuth flows
OpenID - OIDC discovery
3

Configure the Scheme

Fill in the required fields based on your authentication type:

Name:BearerAuth
Type:http
Scheme:bearer
Format:JWT(optional)
4

Apply to Operations

Two ways to require authentication:

Global Security

Add to top-level security array. Applies to all endpoints by default.

Per-Operation

Add to specific operation's security. Overrides global setting.

OAuth 2.0 Configuration

For OAuth 2.0, you'll also need to configure:

  • • Authorization URL - Where users log in
  • • Token URL - Where tokens are exchanged
  • • Scopes - Permissions (e.g., read:users, write:orders)
  • • Flow type - authorizationCode, implicit, clientCredentials, password

Webhooks Section

OpenAPI 3.1

Define webhooks that your API sends to external services. Available only in OpenAPI 3.1 specs.

Webhooks1
orderCreated

Fired when a new order is placed

POST

Managing Webhooks

OpenAPI 3.1+

Webhooks document the HTTP callbacks your API makes to external systems. Here's how to manage them:

Creating a Webhook
  1. Ensure your spec is OpenAPI 3.1 (webhooks aren't supported in 3.0)
  2. Click "+ Add Webhook" in the Webhooks section
  3. Enter a descriptive name (e.g., orderCreated)
  4. Define the request method (usually POST)
  5. Specify the request body schema that will be sent
  6. Document expected responses from the receiving server
Webhook Structure
webhooks:
orderCreated:
post:
summary: New order notification
description: Sent when a customer places an order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEvent'
responses:
'200':
description: Webhook received successfully
Good Practices
  • • Include event type in the payload
  • • Add timestamp for ordering
  • • Include idempotency key
  • • Document retry behavior
  • • Define signature header for verification
Common Events
  • • order.created
  • • payment.completed
  • • user.registered
  • • subscription.cancelled
  • • invoice.paid

OpenAPI 3.0 Alternative

If you need webhook-like documentation in OpenAPI 3.0, use operation-level callbacks instead. Callbacks are tied to specific operations and use runtime expressions for the callback URL.

Callbacks (Operation-level)

OpenAPI 3.0+

Callbacks define asynchronous, out-of-band requests that your API makes in response to certain events. Unlike webhooks, callbacks are tied to specific operations.

Callbacks (3.0+)
  • • Tied to a specific operation
  • • URL uses runtime expressions
  • • Triggered by the operation's response
  • • Example: Payment notification after checkout
Webhooks (3.1+)
  • • Standalone, not tied to operations
  • • URL configured externally
  • • Triggered by any event
  • • Example: Order status change event
Callback Structure
paths:
/subscribe:
post:
summary: Subscribe to events
callbacks:
onEvent:
'{$request.body#/callbackUrl}':
post:
summary: Event notification
requestBody:
$ref: '#/components/...'

The callback URL is extracted from the request body using a runtime expression.

Adding Callbacks in Visual Designer
  1. Navigate to Paths section and expand an operation
  2. Scroll to the "Callbacks" subsection
  3. Click "+ Add Callback"
  4. Enter callback name and runtime expression URL
  5. Define the callback's request/response schema
Code EditorSchema Composition