OpenAPI description

Overview

OpenAPI is a specification for describing REST API interfaces. The OpenAPI Specification (OAS) is both human and machine-readable.

The OpenAPI Description (OAD) represents a formal description of an API and is often published by a service provider as a JSON or YAML file. The description can be used to generate client libraries, documentation, and other tools.

See OpenAPI Specification v3.1.0 and OpenAPI Initiative for more information.

Yoco’s OpenAPI description

We provide a publicly accessible OpenAPI 3.1 description of our REST API at https://api.yoco.com/openapi.json.

Using the OpenAPI description

Because the OpenAPI description is machine-readable, there are many publicly available tools that can be used to generate client libraries, documentation, and test API integrations.

Here are some common use-cases:

• Generate client libraries using OpenAPI Generator
• Generate documentation using Swagger UI
• Mock an API using Prism
• Import OpenAPI definition into Postman and Bruno.

Generating an API client using OpenAPI Generator

We recommend using OpenAPI Generator to generate client libraries.

$
npm install @openapitools/openapi-generator-cli -g

$
openapi-generator-cli version

7.16.0

$
openapi-generator-cli list

The following generators are available:
CLIENT generators:
    - ada
    - android
    - apex
    - bash
    - c
    - clojure
    ...

$
openapi-generator-cli generate -g typescript -o yoco-typescript-client -i https://api.yoco.com/openapi.json

Generating a Python API client using openapi-python-client

We recommend using openapi-python-client to generate a client library for Python. It is a more modern alternative that has strong typing, better support for async and leverages Pydantic for data models and validation.

$
pipx install openapi-python-client --include-deps

$
openapi-python-client generate --url https://api.yoco.com/openapi.json

1
from yoco_api_client import AuthenticatedClient
2
from yoco_api_client.api.orders import list_orders_v1_orders_get
3
from yoco_api_client.models import ErrorResponse, PaginatedResponseOrder
4
5
client = AuthenticatedClient(
6
    base_url="https://api.yoco.com",
7
    token="ThisIsAnOAuthAccessToken"
8
)
9
10
with client as client:
11
    response = list_orders_v1_orders_get.sync(client=client)
12
13
    if isinstance(response, PaginatedResponseOrder):
14
        print(f"Received paginated order response: ", response)
15
16
        for order in response.data:
17
            print(order.id)
18
    elif isinstance(response, ErrorResponse):
19
        raise Exception(f"Received HTTP status code {response.status}: {response.detail}")