api-platform / api-platform/docs
Document `#[NotExposed]` for nested DTOs in design.md and dto.md
- Lingua principale
- Nessun dato sulla lingua
- Stelle
- 181
- Fork
- 1.1k
- Merge medio
- 1g 16h
- PR unite (30g)
- 20
Descrizione
## Context
`#[NotExposed]` is currently documented only in [jsonapi.md](https://github.com/api-platform/docs/blob/main/core/jsonapi.md) (for JSON:API relations) and briefly mentioned in [openapi.md](https://github.com/api-platform/docs/blob/main/core/openapi.md). It is missing from the two pages most users land on when designing DTOs:
- [`core/design.md`](https://github.com/api-platform/docs/blob/main/core/design.md)
- [`core/dto.md`](https://github.com/api-platform/docs/blob/main/core/dto.md)
## Problem
API Platform's metadata pipeline (Hydra docs, OpenAPI, JSON Schema, property security, etc.) walks `#[ApiResource]` classes only. Nested POPOs referenced via property typehints are invisible to the doc generators. Users hit this repeatedly (e.g. https://github.com/api-platform/core/issues/8187, https://github.com/api-platform/core/issues/8087) and the typical answer — \"mark the nested DTO with `#[NotExposed]`\" — is not discoverable from the DTO docs.
## Suggested addition
Short subsection in `dto.md` (and a mention in `design.md`) covering:
- Nested DTOs referenced from an output DTO are not introspected for docs unless they are themselves resources
- Use `#[NotExposed]` on a nested DTO to register its metadata (Hydra/OpenAPI/property factories) without exposing public endpoints
- Brief example:
```php
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\NotExposed;
#[ApiResource(operations: [new Get(/* ... */)])]
class Response
{
/** @var Nested[] */
public array $data = [];
}
#[NotExposed]
class Nested
{
public function __construct(public int $id) {}
}
```
- Cross-link to the existing `NotExposed` reference in `jsonapi.md`
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.