OpenAPI spec: PokemonSprites only declares front_default, but the API returns many more fields #1710

Describe the Bug

On master, openapi.yml defines the sprites of PokemonDetail through the PokemonSprites schema, which only declares front_default:

PokemonSprites:
  type: object
  properties:
    front_default:
      type:
      - string
      - 'null'
  required:
  - front_default

The schema comes from PokemonSpritesSerializer in pokemon_v2/serializers.py, which currently only has front_default = serializers.CharField(allow_null=True).

The real response of /api/v2/pokemon/25/ has more keys under sprites:

• front_default, front_shiny, front_female, front_shiny_female, back_default, back_shiny, back_female, back_shiny_female
• other (with home, showdown, dream_world and official-artwork)
• versions

As a result, a client generated from the spec (I used @hey-api/openapi-ts 0.99.0) gets:

export type PokemonSprites = {
    front_default: string | null;
};

and code that reads pokemon.sprites.other fails to type-check (Property 'other' does not exist on type 'PokemonSprites'), even though the field is present in the API response.

This used to be different. I generated a client from openapi.yml at 5064f1d (before the August 11 serializer/typehints work) and got:

readonly sprites: {
    front_default?: string;
    [key: string]: string | undefined;
};

In that version, the pokemon sprites was an inline object with front_default plus additionalProperties (string, nullable). The extra keys were not declared individually (and other was typed as string | undefined, which is not accurate either), but accessing them compiled. The schema first changes to the front_default-only version in 2bf3e19 ("feat: Add typehints to serializer.py and fix ruff lint issues", which regenerates openapi.yml, where it appears as _PokemonSpritesDetail); 83eb836 then renames it to PokemonSprites.

I don't know whether dropping those fields from the spec was intentional.

Related: #1129 reports PokemonSprites.other as undocumented in the docs; this issue is about the OpenAPI schema.

Steps to Reproduce

1. Download openapi.yml from master.
2. Generate a TypeScript client with @hey-api/openapi-ts 0.99.0 and look at PokemonSprites in types.gen.ts: it only has front_default.
3. Compare with curl https://pokeapi.co/api/v2/pokemon/25/ | jq '.sprites | keys', which also lists other, versions and the back_* / front_* variants.

Resolving the Bug

Anyone is open to making a PR for this issue.