Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

🎸Dynamic OpenAPI Schema Naming Based on DTO Namespace

Open
  • Is something wrong?
#8,162 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
openapi, php
Domain
api, backend-api-design

Research direction

Start by reviewing the OpenApiFactory naming strategy and the proposed config location in config/packages/api_platform.yaml. Determine how DTO namespaces and Model context folders would be resolved, then verify that input and output schemas receive the requested EntryPoint.Context.ClassName keys without collisions.

Written by the indexing model from the issue text.

Description

OpenAPI

Feature Request: Dynamic OpenAPI Schema Naming Based on DTO Namespace

📦 Background

By default, API Platform generates OpenAPI schemas using the “short name” of each DTO, which often leads to collisions and unclear schema names when multiple operations share the same class name (e.g. ResetPasswordInput). We have a custom decorator today that post-processes the OpenAPI components and renames schemas at runtime to {EntryPoint}.{Context}.{DTO}, but this requires complex workarounds and still depends on heuristics or introspection of generated schema names.

🚩 Problem

  • Schema collisions when different operations share DTO class names (e.g. ResetPasswordInput in “request” and “perform” flows).

  • Lack of clarity: consumers see only the short class name, not the context (“Request” vs “Reset”) nor the entrypoint.

  • Complex custom decorators required to hack around built‑in naming logic.

🎯 Desired Behavior

When you define DTOs under a folder structure like:

src/ApiResource/
└── Auth
    └── ResetPassword
        ├── Model
        │   ├── Request
        │   │   └── ResetPasswordInput.php
        │   └── Reset
        │       └── ResetPasswordInput.php
        └── ResetPasswordEntryPoint.php

  1. OpenAPI schema key should become

    ResetPasswordEntryPoint.Request.ResetPasswordInput.jsonld
ResetPasswordEntryPoint.Reset.ResetPasswordInput.jsonld

  2. It should work automatically for any module/feature/folder under ApiResource/{Module}/{Feature}/Model/{Context}/{DTO}.php.

  3. No extra configuration (no manual _api_operation_name overrides) or fragile heuristics based on class metadata.

💡 Proposed Solution

Enhance API Platform’s OpenAPI naming strategy to:

  1. Extract the resource entrypoint (folder name + “EntryPoint”).

  2. Extract the context folder under Model (e.g. Request, Reset).

  3. Use the DTO class name.

  4. Compose the OpenAPI schema key as {EntryPoint}.{Context}.{ClassName}, automatically for all input/output DTOs.

This could live inside the core OpenApiFactory or as a first‑class feature behind a config flag, e.g.:

# config/packages/api_platform.yaml
api_platform:
  openapi:
    dynamic_schema_naming: true

Benefits:

  • Eliminates custom decorator hacks.

  • Prevents name collisions entirely.

  • Provides clear, self‑documenting schema names.

🔧 Example Before/After
Before After
components.schemas.ResetPasswordInput.jsonld components.schemas.ResetPasswordEntryPoint.Request.ResetPasswordInput
components.schemas.ResetPasswordInput_1.jsonld components.schemas.ResetPasswordEntryPoint.Reset.ResetPasswordInput

Please consider adding this as an official enhancement to API Platform’s OpenAPI generator. It aligns with the directory‑based organization of DTOs and greatly improves developer experience and schema clarity.
Thank you! 🚀

Dominant language
PHP
Stars
2.6k
Forks
989
Avg merge
2d 1h
Merged PRs (30d)
104

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from api-platform/core

All issues in api-platform/core

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.