🎸Dynamic OpenAPI Schema Naming Based on DTO Namespace

Offen
  • Stimmt etwas nicht?
#8,162 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
30/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
openapi, php
Bereich
api, backend-api-design

Rechercherichtung

Beginne mit der Überprüfung der Benennungsstrategie von OpenApiFactory und des vorgeschlagenen Konfigurationsorts in config/packages/api_platform.yaml. Ermittle, wie DTO-Namespaces und Model-Kontextordner aufgelöst würden, und verifiziere anschließend, dass Eingabe- und Ausgabeschemas die angeforderten EntryPoint.Context.ClassName-Schlüssel ohne Kollisionen erhalten.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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

Vorherrschende Sprache
PHP
Sterne
2.6k
Forks
987
Ø Merge
2 T. 5 Std.
Gemergte PRs (30 T.)
73

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus api-platform/core

Alle Issues in api-platform/core

Ähnliche Issues

Weitere Issues zu PHP

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.