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

A publicly accessible OpenAPI 3.1 description of the REST API is available 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

OpenAPI Generator is recommended for generating 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

openapi-python-client is recommended for generating 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}")