Example Generation¶

Generate deterministic example UUIDs and display IDs for documentation and OpenAPI schemas.

Why Deterministic Examples?¶

When generating API documentation, you want example values that:

Stay consistent across documentation regenerations
Match the expected format (correct prefix, valid base62)
Look realistic (not obviously fake like 00000000-...)

The example functions produce the same output for the same input, making your docs stable and predictable.

Functions¶

example_uuid¶

Generate a deterministic UUID from a prefix or model.

from django_display_ids import example_uuid

# From prefix string
u = example_uuid("inv")
# -> UUID('a172cedc-ae47-474b-...')

# From model class
u = example_uuid(Invoice)
# -> same UUID (uses Invoice.display_id_prefix)

The same prefix always produces the same UUID.

example_display_id¶

Generate a deterministic display ID from a prefix or model.

from django_display_ids import example_display_id

display_id = example_display_id("inv")
# -> "inv_4ueEO5Nz4X7u9qc3FVHokM"

display_id = example_display_id(Invoice)
# -> same display ID

Usage with drf-spectacular¶

Use example functions to create consistent OpenAPI schemas:

from drf_spectacular.utils import extend_schema, OpenApiExample
from django_display_ids import example_display_id, example_uuid

@extend_schema(
    examples=[
        OpenApiExample(
            "Invoice Response",
            value={
                "id": str(example_uuid("inv")),
                "display_id": example_display_id("inv"),
                "name": "Q1 2024 Invoice",
            },
        ),
    ],
)
class InvoiceViewSet(ModelViewSet):
    ...

The DisplayIDField serializer field uses these functions automatically when generating its schema examples.

How It Works¶

The functions use a deterministic hash of the prefix to generate a UUID. The algorithm is stable across Python versions and library updates.

# Simplified implementation concept:
# 1. Hash the prefix string
# 2. Use hash bytes to construct a UUID
# 3. Result is always the same for the same prefix