api-platform / api-platform/docs

Document `#[NotExposed]` for nested DTOs in design.md and dto.md

Aperta
#2,284 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.