OpenAPI specifications
Specifications generated from your data models - downloads, the HTTP endpoint and the console.
The platform generates OpenAPI specifications for your REST APIs - definitions of endpoints, request and response schemas and security requirements in the standard format that Postman, API gateways and code generators understand.
The specifications are built from data models defined in your services. When you assign a model to a service's input or output, Zato extracts the schema information from the dataclass and the generated document carries it.
OpenAPI console
The primary surface is the OpenAPI console - a live, browsable portal where the document is generated from the deployed services themselves, filtered per caller and paired with a try-it client. It requires no channels, no exports and no configuration:
- Using the OpenAPI console - for API consumers, signing in, browsing and invoking endpoints
- OpenAPI administration - for operators, architecture, which channels are documented, auto-created channels, branding
- OpenAPI and API management - the overview of the whole layer
- API management documentation - everything else the layer includes, from quota tiers to analytics
Independently of the console, you can also produce downloadable specification files in two ways:
- Dashboard - download OpenAPI YAML files directly from the web interface
- OpenAPI endpoint - access specifications over HTTP with authentication
Create an OpenAPI channel
An OpenAPI channel groups multiple REST channels into a single API specification. To create one, go to Connections > Channels > OpenAPI in the Dashboard, click Create an OpenAPI channel and fill in the form:
- Name: My API v2
- REST channels: the channels to include in this specification
- Click OK
The channel name is slugified into the URL path of the OpenAPI endpoint - a channel named My API v2 becomes accessible at /openapi/my-api-v2.
Assign REST channels
In the OpenAPI channel's edit form, the REST channels section lists every REST channel with a tri-state checkbox:
- On - the channel appears in the specification
- Off - the channel does not appear
- Disabled (an "x" sign) - the channel is temporarily excluded, kept in the list for when it returns
Only channels marked On appear in the generated specification, and a single REST channel may be part of more than one OpenAPI channel.
Download the specification
In the channel list under Connections > Channels > OpenAPI, each channel's row has a Download OpenAPI link that serves the complete YAML file, containing:
- API paths and HTTP methods
- Request body schemas, from your service
inputdefinitions - Response schemas, from your service
outputdefinitions - Security schemes - the Basic Auth and API key definitions of the REST channels
Example output
A service with typed input and output models:
# -*- coding: utf-8 -*-
# stdlib
from dataclasses import dataclass
# Zato
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) -> 'None':
pass
The generated specification carries the 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
Access OpenAPI over HTTP
Each OpenAPI channel is served at its own HTTP endpoint:
The endpoint requires HTTP Basic Auth credentials matching one of the REST channels included in the OpenAPI channel - if any of those channels has a Basic Auth security definition, its credentials open the specification:
A request with missing or invalid credentials receives HTTP 403 Forbidden.
Example
With an OpenAPI channel named my-api and a REST channel secured by a Basic Auth definition whose username is apiuser:
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
See also
| Page | What it covers |
|---|---|
| OpenAPI console | The live documentation portal with a try-it client |
| REST channels | The channels and data models the specifications describe |
| Authentication | The security definitions the specifications document |
| API versioning | How deprecated endpoints appear to specification readers |