OpenAPI specifications

Zato can generate OpenAPI specifications for your REST APIs. OpenAPI definitions describe your API endpoints, request/response schemas, and security requirements in a standard format that tools like Swagger UI, Postman, API gateways, and code generators understand.

OpenAPI specs are built from data models defined in your services. Models are Python dataclasses that describe the structure of your request and response objects. When you assign a model to a service's input or output, Zato automatically extracts the schema information to generate the OpenAPI specification.

You can generate OpenAPI specs in two ways:

Dashboard - Download OpenAPI YAML files directly from the web interface
OpenAPI endpoint - Access specifications programmatically via HTTP with authentication

Dashboard

Creating an OpenAPI channel

OpenAPI channels group multiple REST channels together into a single API specification. To create one:

Go to Connections → Channels → OpenAPI
Click Create an OpenAPI channel and fill out the form

Configuration fields:

Field	Purpose
Name	Unique identifier for this OpenAPI channel
REST channels	The REST channels to include in this specification

The channel name is automatically slugified to create the URL path for the OpenAPI endpoint. For example, a channel named My API v2 becomes accessible at /openapi/my-api-v2.

Adding REST channels

After creating the OpenAPI channel, add REST channels to it:

Edit the OpenAPI channel
In the REST channels section, use the tri-state checkbox to configure each channel:
- On - Include this channel in the OpenAPI specification
- Off - Exclude this channel from the specification
- Disabled ("x" sign) - Channel is temporarily disabled - this is useful when, just for the time being, prevent a channel from appearing the OpenAPI spec

A single channel may be a part of more than one OpenAPI spec, and only channels marked as On will appear in the generated OpenAPI specification, so in the screenshot above, neither of them will, because the first one is disabled and the other is off.

Downloading the specification

To download the OpenAPI YAML file:

Go to Connections → Channels → OpenAPI
Find your channel in the list
Click Download OpenAPI

The downloaded file contains the complete OpenAPI specification including:

API paths and HTTP methods
Request body schemas (from your service input definitions)
Response schemas (from your service output definitions)
Security schemes (Basic Auth and API key definitions from your REST channels)

Example output

For a service with typed input/output models:

from dataclasses import dataclass
from zato.server.service import Model, Service

@dataclass(init=False)
class GetCustomerRequest(Model):
    customer_id: str

@dataclass(init=False)
class GetCustomerResponse(Model):
    name: str
    email: str

class GetCustomer(Service):
    name = 'customer.get'
    input = GetCustomerRequest
    output = GetCustomerResponse

    def handle(self):
        pass

The generated OpenAPI will include full schemas:

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /api/customer:
    post:
      summary: Invoke customer.get
      operationId: customer_get
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCustomerRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
      security:
        - my-basic-auth: []
components:
  schemas:
    GetCustomerRequest:
      type: object
      properties:
        customer_id:
          type: string
      required:
        - customer_id
    GetCustomerResponse:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
      required:
        - name
        - email
  securitySchemes:
    my-basic-auth:
      type: http
      scheme: basic

OpenAPI endpoint

You can also access OpenAPI specifications programmatically via HTTP. See the OpenAPI endpoint tab for details.

OpenAPI endpoint

Accessing OpenAPI via HTTP

Zato exposes an HTTP endpoint for programmatic access to OpenAPI specifications:

GET /openapi/{channel-name}

This endpoint requires HTTP Basic Auth credentials matching one of the REST channels included in the OpenAPI channel.

Authentication

The endpoint validates credentials against the Basic Auth security definitions attached to the REST channels in your OpenAPI channel. If any REST channel in the OpenAPI channel has a Basic Auth security definition, those credentials can be used to access the specification.

curl -u username:password http://localhost:17010/openapi/my-api

If credentials are missing or invalid, the endpoint returns HTTP 403 Forbidden.

Example

Assuming you have:

An OpenAPI channel named my-api
A REST channel with Basic Auth security pubapi (username: apiuser, password: secret123)

Access the specification:

curl -u apiuser:secret123 http://localhost:17010/openapi/my-api

Response:

openapi: 3.1.0
info:
  title: my-api
  version: 1.0.0
paths:
  /api/customer:
    post:
      summary: Invoke customer.get
      operationId: customer_get
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
      security:
        - pubapi: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCustomerRequest'
components:
  schemas:
    GetCustomerRequest:
      type: object
      properties:
        customer_id:
          type: string
      required:
        - customer_id
    GetCustomerResponse:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
      required:
        - name
        - email
  securitySchemes:
    pubapi:
      type: http
      scheme: basic

Learn more

REST integration overview Start here to see how teams build REST integrations

In-depth API tutorial Master architectural patterns for production-ready integrations

Modern REST API tutorial Design, build and secure REST APIs with Python