OpenAPI et spécifications API

  • Les services avec models peuvent être exportés vers OpenAPI ou vers des spécifications API complètes.
  • Notez que votre service ne doit pas nécessairement être un service REST pour que l'OpenAPI fonctionne - par exemple, si vous avez un service auquel on accède uniquement en arrière-plan à partir d'un planificateur ou uniquement par le biais de WebSockets, sa définition peut toujours être exportée.

Un exemple de modèle commercial à mettre en œuvre peut ressembler à ceci :

Voici un exemple de service qui répond à ce modèle. Notez que nous sautons son implémentation réelle dans la méthode handle car elle n'influence pas le processus d'exportation vers OpenAPI ou les spécifications API.

# -*- 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

Utilisez zato openapi depuis la ligne de commande pour exporter des services vers OpenAPI:

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

Les invoquer dans Postman ou d'autres outils compatibles avec OpenAPI :

Spécifications complètes de l'API

Utilisez zato apispec à partir de la ligne de commande pour générer des spécifications d'API complètes, comprenant à la fois un site HTML statique et une interface OpenAPI.

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

Page d'accueil:

Détails d'un service particulier:

Sujets connexes