Improving OpenAPI Schema Naming Strategy #2907

Hi everyone,

I’d like to start a discussion around enhancing API Platform’s OpenAPI generator to support dynamic, directory‑based schema naming (feature request: see #2906). Currently, schema keys default to the DTO’s “short name,” which leads to collisions and unclear documentation when multiple operations share the same class name (for example, ResetPasswordInput used both for “request” and “perform” flows).

🎯 Goals

1. Clear, collision‑free schema names
   Automatically generate keys in the pattern:

   {EntryPoint}.{Context}.{DTO}
   

   For example:

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

2. Zero configuration overhead
   No need for manual _api_operation_name overrides or custom decorators. The naming should mirror the folder structure under:

   src/ApiResource/{Module}/{Feature}/Model/{Context}/{DTO}.php
   

3. Backward‑compatible opt‑in
   Expose behind a config flag, e.g.:

   api_platform:
     openapi:
       dynamic_schema_naming: true

🔧 Why This Matters

• Prevents name collisions when different endpoints share class names.
• Improves self‑documentation, making it obvious which operation and context each schema belongs to.
• Eliminates fragile hacks (like custom OpenApiFactory decorators) that parse and rename schemas post‑hum.

📚 Related

• Feature request issue: https://github.com/api-platform/api-platform/issues/2906

I’d love to gather feedback on:

• Is this in scope for the core library?
• Would a config flag be enough?
• Any concerns around performance or edge cases?