OpenAPI and API specifications

  • Services with models can be exported to OpenAPI or to full API specifications
  • Note that your service does not to be a REST one for OpenAPI to work - e.g. if you have a service that is only accessed in background from a scheduler or only through WebSockets, its definition can be still exported

A sample business model to be implemented may look like this:

Here is a a sample service that fulfils this model. Note that we are skipping its actual implementation in the handle method because it does not influence the process of exporting it to OpenAPI or API specifications.

# -*- coding: utf-8 -*-

# stdlib
from dataclasses import dataclass

# Zato
from zato.common.typing_ import list_
from zato.server.service import Model, Service

# ###########################################################################

@dataclass(init=False)
class Phone(Model):
    imei:       str
    owner_id:   int
    owner_name: str

# ###########################################################################

@dataclass(init=False)
class GetPhoneListRequest(Model):
    client_id: int

@dataclass(init=False)
class GetPhoneListResponse(Model):
    phone_list:    list_[Phone]
    response_type: str

# ###########################################################################

class GetPhoneDetails(Service):

    class SimpleIO:
        input  = GetPhoneListRequest
        output = GetPhoneListResponse

    def handle(self):
        # Skipped implementation
        ...

# ###########################################################################

OpenAPI

Use zato openapi from command line to export services to OpenAPI:

$ zato openapi /path/to/server \
  --include "phone*" \
  --file /tmp/test-openapi.yaml

Invoke them in Postman or other OpenAPI-compatible tools:

Full API specifications

Use zato apispec from command line to generate full API specifications, including both a static HTML site as well as OpenAPI.

$ zato apispec /path/to/server \
  --include "phone*" \
  --file /tmp/test-openapi.yaml

Main page:

Details of a particular service: