Skip to content

Generate all models and TypedDicts from the OpenAPI spec #758

Description

@vdusek

Context

The client currently keeps a small set of hand-written Pydantic models and TypedDicts alongside the generated ones:

  • src/apify_client/_models.pyActorJob, ActorJobResponse, WebhookRepresentation, WebhookRepresentationList, RequestInput, RequestDeleteInput
  • src/apify_client/_typeddicts.pyRequestInputDict, RequestDeleteInputDict, WebhookRepresentationDict

These shapes are hand-maintained because they are not exposed as reusable components in the OpenAPI spec at https://docs.apify.com/api/openapi.json — typically because each shape is only used at a single endpoint, so the spec inlines it instead of promoting it to components/schemas.

Per discussion with the API docs team: if we extract those inlined shapes into components/schemas in the source spec, datamodel-code-generator will pick them up and emit them into _models_generated.py / _typeddicts_generated.py automatically, and we can drop the hand-written copies.

Proposal

For each shape currently living in _models.py / _typeddicts.py:

  1. In the apify/apify-docs OpenAPI source, extract the inline schema into a named entry under components/schemas and reference it from the endpoint(s) that use it.
  2. Once the spec change is published, regenerate locally with uv run poe generate-models and verify the new model/TypedDict matches the hand-written one (field names, aliases, optionality, defaults).
  3. Remove the hand-written definition and update imports to pull from _models_generated / _typeddicts_generated.

Shapes that carry local-only logic (e.g. RequestDeleteInput's _check_at_least_one_identifier validator, WebhookRepresentationList.from_webhooks / to_base64) still need a thin hand-written layer, but the base schema itself can come from the generator.

Goal

_models.py and _typeddicts.py shrink to only the shapes that genuinely need hand-written logic (validators, helper methods), with all base schemas sourced from the OpenAPI spec. This removes the manual drift risk between the spec and the client.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

t-toolingIssues with this label are in the ownership of the tooling team.

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions