Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

🎸Dynamic OpenAPI Schema Naming Based on DTO Namespace

Aperta
  • Qualcosa non va?
#8,162 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
openapi, php
Ambito
api, backend-api-design

Direzione di ricerca

Inizia esaminando la strategia di denominazione di OpenApiFactory e la posizione di configurazione proposta in config/packages/api_platform.yaml. Determina come verrebbero risolti i namespace DTO e le cartelle di contesto Model, quindi verifica che gli schemi di input e output ricevano le chiavi EntryPoint.Context.ClassName richieste senza collisioni.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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! 🚀

Lingua principale
PHP
Stelle
2.6k
Fork
989
Merge medio
2g 1h
PR unite (30g)
104

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di api-platform/core

Tutte le issue di api-platform/core

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.