api-platform / api-platform/docs

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

Open
#2,284 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
181
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
20

Description

## 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`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.