Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

🎸Dynamic OpenAPI Schema Naming Based on DTO Namespace

Đang mở
  • Có gì không ổn?
#8,162 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
30/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi, php
Lĩnh vực
api, backend-api-design

Hướng nghiên cứu

Bắt đầu bằng việc xem xét chiến lược đặt tên của OpenApiFactory và vị trí cấu hình được đề xuất trong config/packages/api_platform.yaml. Xác định cách các namespace của DTO và các thư mục context của Model sẽ được phân giải, sau đó xác minh rằng các schema input và output nhận được các khóa EntryPoint.Context.ClassName được yêu cầu mà không xảy ra xung đột.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Ngôn ngữ chính
PHP
Star
2.6k
Fork
989
Merge trung bình
1 ngày 23 giờ
Pull request đã merge (30 ngày)
102

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của api-platform/core

Tất cả issue của api-platform/core

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.