Symfony + NelmioApiDocBundle を使ったスキーマ駆動開発 / Schema Driven Development with NelmioApiDocBundle

Symfony + NelmioApiDocBundle を使ったスキーマ駆動開発 2026-03-20 PHPerKaigi 2026

所属：株式会社リンケージ運営：ぺちぱーティーナイト、TechGYOZA 寄稿：好き：音楽ゲーム（IIDX, DDR, Arcaea, BPL 観戦）、 Stardew
Valley、謎解き、観葉植物岡田正平／おかしょい X: @okashoi GitHub: @okashoi \ シルバースポンサー /

スキーマ駆動開発のメリットは（なんとなくでも）わかる • けどしっくり来てない／実践方法を模索している • API スキーマを書くのに苦戦している PHP にある程度習熟しているチーム • 「静的解析は導入してますよ」という感じだと
better このトークを聴くのがオススメな対象者

「メリットとかよくわからん......」という方向け https://fortee.jp/phperkaigi-2024/proposal/9e2e6c38-d078-4efa-99b4-83ebf9033b34 Laravel OpenAPIによる "辛くない" スキーマ駆動開発 by 武田憲太郎

1. スキーマ駆動開発における課題 01:00～05:00 2. NelmioApiDocBundle 解説 05:00～08:00 3. API エンドポイント実装例
08:00～17:00 4. 注意点・他の選択肢との比較 17:00～19:30 5. まとめ 19:30～20:00 目次（時間は目安）

スキーマ（※）を先に定義し、それを唯一の信頼できる情報源（Single Source of Truth, SSoT）として開発を進めるアプローチ ※このトークでは Web API
スキーマを指すスキーマ駆動開発とは

スキーマ駆動開発とは API スキーマ SSoT

スキーマ駆動開発とは API スキーマ SSoT API クライアント API サーバーの実装

今日はこの辺に絞ってお話をします API スキーマ SSoT API クライアント API サーバーの実装

（この部分は今日は割愛） API スキーマ SSoT API クライアント API サーバーの実装ライブラリ例 ·
openapi-fetch · orval

• フロントエンド、バックエンド開発の疎結合化 • フロントエンド、バックエンド間の認識齟齬防止 • 型定義、バリデーション等の自動化 → これらの恩恵に充分に与るには仕組みの構築が必要スキーマ駆動開発のメリット

• API スキーマをどう表現し、どう管理するか • スキーマと実装の一致をどう担保するか • 型定義、バリデーション等のコードをどう生成するかスキーマ駆動開発における課題

• API スキーマをどう表現し、どう管理するか • スキーマと実装の一致をどう担保するか • 型定義、バリデーション等のコードをどう生成するかスキーマ駆動開発における課題 OpenAPI Speciﬁcation

OpenAPI Speciﬁcation https://swagger.io/speciﬁcation/

OpenAPI Speciﬁcation paths: /pet: put: tags: - pet summary: Update
an existing pet. description: Update an existing pet by Id. operationId: updatePet requestBody: description: Update an existent pet in the store content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Pet' required: true responses: "200": description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' "400": description: Invalid ID supplied "404":

OpenAPI Speciﬁcation を直接書くのは難しい paths: /user: post: requestBody: required: true content:
application/json: schema: type: object properties: name: type: string required: - name $ curl -X POST \ http://localhost/user \ -d '{"name": "okashoi"}'

OpenAPI Speciﬁcation を直接書くのは難しい paths: /user: post: requestBody: required: true content:
application/json: schema: type: object properties: name: type: string required: true $ curl -X POST \ http://localhost/user \ -d '{"name": "okashoi"}' 左記は誤りで name は任意プロパティ扱いのまま

• OpenAPI Speciﬁcation の定義を習得する必要がある • 規模拡大に伴いファイル分割の戦略も考えなきゃ • そもそも JSON か
YAML を正しく書くのが難しい OpenAPI Speciﬁcation を直接書くのは難しい

スキーマ駆動開発採用に伴う課題への解決策の 1 つとして Symfony + NelmioApiDocBundle の実践例を紹介しますこのトークの趣旨

NelmioApiDocBundle https://symfony.com/bundles/NelmioApiDocBundle/current/index.html

NelmioApiDocBundle https://github.com/nelmio/NelmioApiDocBundle

基本機能 OpenAPI Speciﬁcation に準拠した API スキーマの生成特徴 • swagger-PHP をコアにした
Symfony 統合 • ルーティングからパスを検出 • Validator や Serializer の設定の反映 • Swagger UI のホスティング NelmioApiDocBundle 基本機能

NelmioApiDocBundle 基本機能 use OpenApi\Attributes as OA; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route;
#[Route('api/issue')] class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent( required: ['issues'], properties: [ new OA\Property( property: 'issues', type: 'array', items: new OA\Items( required: ['id', 'summary', 'createdAt'], properties: [ new OA\Property(property: 'id', type: 'string', format: 'uuid'), new OA\Property(property: 'summary', type: 'string'), new OA\Property(property: 'createdAt', type: 'string', format: 'date-time'), ], type: 'object', ), ), ], type: 'object', ), )] public function list(): Response { throw new \LogicException('Not implemented');

#[Route('api/issue')] class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent( required: ['issues'], properties: [ new OA\Property( property: 'issues', type: 'array', items: new OA\Items( required: ['id', 'summary', 'createdAt'], properties: [ new OA\Property(property: 'id', type: 'string', format: 'uuid'), new OA\Property(property: 'summary', type: 'string'), new OA\Property(property: 'createdAt', type: 'string', format: 'date-time'), ], type: 'object', ), ), ], type: 'object', ), )] public function list(): Response { throw new \LogicException('Not implemented'); 一般的な Controller

#[Route('api/issue')] class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent( required: ['issues'], properties: [ new OA\Property( property: 'issues', type: 'array', items: new OA\Items( required: ['id', 'summary', 'createdAt'], properties: [ new OA\Property(property: 'id', type: 'string', format: 'uuid'), new OA\Property(property: 'summary', type: 'string'), new OA\Property(property: 'createdAt', type: 'string', format: 'date-time'), ], type: 'object', ), ), ], type: 'object', ), )] public function list(): Response { throw new \LogicException('Not implemented'); これ自体は swagger-PHP の Attriutes

API スキーマ生成 ./bin/console nelmio:apidoc:dump --format=yaml # 略 # : /api/issue:
get: operationId: app_issue_list responses: '200': description: 'List of issues' content: application/json: schema: required: - issues properties: issues: { type: array, items: { required: [id, summary, createdAt], properties: { id: { type: string, format: uuid }, summary: { type: string }, createdAt: { type: string, format: date-time } }, type: object } } type: object

Swagger UI のホスティング /api/doc （デフォルト設定）

ここまではまださほど嬉しくない（むしろ煩雑になってるだけ）

これを use OpenApi\Attributes as OA; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; #[Route('api/issue')]
class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent( required: ['issues'], properties: [ new OA\Property( property: 'issues', type: 'array', items: new OA\Items( required: ['id', 'summary', 'createdAt'], properties: [ new OA\Property(property: 'id', type: 'string', format: 'uuid'), new OA\Property(property: 'summary', type: 'string'), new OA\Property(property: 'createdAt', type: 'string', format: 'date-time'), ], type: 'object', ), ), ], type: 'object', ), )] public function list(): Response

こうできる use App\UseCase\Issue\ListIssues\ListIssuesOutput; use Nelmio\ApiDocBundle\Attribute\Model; use OpenApi\Attributes as OA; use
Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; #[Route('api/issue')] class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent(ref: new Model(type: ListIssuesOutput::class)), )] public function list(): Response { throw new \LogicException('Not implemented'); }

こうできる use App\UseCase\Issue\ListIssues\ListIssuesOutput; use Nelmio\ApiDocBundle\Attribute\Model; use OpenApi\Attributes as OA; use
Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; #[Route('api/issue')] class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent(ref: new Model(type: ListIssuesOutput::class)), )] public function list(): Response { throw new \LogicException('Not implemented'); } ref: new Model(type: ListIssuesOutput::class) Plain Old PHP Object（POPO）で OK

PHP のクラスが schemas として扱われる use App\UseCase\Issue\ListIssues\ListIssuesOutput; use Nelmio\ApiDocBundle\Attribute\Model; use OpenApi\Attributes
as OA; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; #[Route('api/issue')] class IssueController { #[Route('', methods: ['GET'])] #[OA\Response( response: 200, description: 'List of issues', content: new OA\JsonContent(ref: new Model(type: ListIssuesOutput::class)), )] public function list(): Response { throw new \LogicException('Not implemented'); } /api/issue: get: operationId: app_issue_list responses: '200': description: 'List of issues' content: application/json: schema: $ref: '#/components/schemas/ListIssuesOutput'

PHP の型情報をよしなに解釈してくれる #[OA\Response( response: 200, description: 'List of issues', content:
new OA\JsonContent(ref: new Model(type: ListIssuesOutput::class)), )]

new OA\JsonContent(ref: new Model(type: ListIssuesOutput::class)), )] <?php declare(strict_types=1); namespace App\UseCase\Issue\ListIssues; readonly class ListIssuesOutput { /** * @param list<IssueListItem> $issues */ public function __construct( public array $issues, ) { } }

new OA\JsonContent(ref: new Model(type: ListIssuesOutput::class)), )] <?php declare(strict_types=1); namespace App\UseCase\Issue\ListIssues; readonly class ListIssuesOutput { /** * @param list<IssueListItem> $issues */ public function __construct( public array $issues, ) { } } <?php declare(strict_types=1); namespace App\UseCase\Issue\ListIssues; use Symfony\Component\Uid\Uuid; readonly class IssueListItem { public function __construct( public Uuid $id, public string $summary, public \DateTimeImmutable $createdAt, ) { } }

PHP の型情報をよしなに解釈してくれる <?php declare(strict_types=1); namespace App\UseCase\Issue\ListIssues; use Symfony\Component\Uid\Uuid; readonly class
IssueListItem { public function __construct( public Uuid $id, public string $summary, public \DateTimeImmutable $createdAt, ) { } } components: schemas: IssueListItem: required: - id - summary - createdAt properties: id: type: string format: uuid summary: type: string createdAt: type: string format: date-time type: object

その他にも • PHP の列挙型（Enum）は enum • PHP の Union 型
は oneOf になる PHP の型情報をよしなに解釈してくれる

プロパティ単位で Attributes 付与も可能 <?php declare(strict_types=1); namespace App\UseCase\User\GetUserDetail; use OpenApi\Attributes as
OA; use Symfony\Component\Uid\Uuid; readonly class GetUserDetailOutput { public function __construct( public Uuid $id, #[OA\Property(minLength: 5)] public string $name, #[OA\Property(format: 'email')] public string $email, ) { } GetUserDetailOutput: required: - id - name - email properties: id: type: string format: uuid name: type: string minLength: 5 email: type: string format: email type: object

• OpenAPI Speciﬁcation 準拠の API スキーマ生成 • Controller に Attributes
を付与することで定義 • POPO のプロパティの型情報をよしなに解釈してくれる NelmioApiDocBundle まとめ

• OpenAPI Speciﬁcation 準拠の API スキーマ生成 • Controller に Attributes
を付与することで定義 • POPO のプロパティの型情報をよしなに解釈してくれる NelmioApiDocBundle まとめ嬉しいポイント

参考実装 https://github.com/okashoi/symfony-schema-driven-development

スキーマ駆動開発とは（再掲） API スキーマ SSoT API クライアント API サーバーの実装

NelmioApiDocBundle を使ったスキーマ駆動開発 OpenAPI Speciﬁcation POPO / Attributes API クライアント API
サーバーの実装 SSoT

NelmioApiDocBundle を使ったスキーマ駆動開発 OpenAPI Speciﬁcation POPO / Attributes API クライアント API
サーバーの実装 SSoT SSoT を PHP で表現できる

SSoT を PHP で表現できる → PHP に習熟しているチームほど恩恵が大きい • API エンドポイントの実装に型を直接利用できる
• 使い慣れた IDE, 静的解析ツールを利用できる NelmioApiDocBundle を使ったスキーマ駆動開発

「課題作成 API」実装例全体像 #[Route('', methods: ['POST'])] #[OA\RequestBody( required: true, content:
new OA\JsonContent(ref: new Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); }

new OA\JsonContent(ref: new Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } API 定義部分

new OA\JsonContent(ref: new Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } 実装部分

#[Route('', methods: ['POST'])] #[OA\RequestBody( required: true, content: new OA\JsonContent(ref: new
Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } リクエスト／レスポンス（正常系）定義 #[OA\RequestBody( required: true, content: new OA\JsonContent(ref: new Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )]

リクエストボディの定義（POPO） use OpenApi\Attributes as OA; use Symfony\Component\Validator\Constraints as Assert; readonly
class CreateIssueInput { public function __construct( #[OA\Property(minLength: 1)] #[Assert\NotBlank] public string $summary, ) { } } Symfony の Validation と併用も可

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } MapRequestPayload によるオブジェクトへの変換

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } MapRequestPayload によるオブジェクトへの変換 #[MapRequestPayload] CreateIssueInput $input, CreateIssueInput::class

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } MapRequestPayload によるオブジェクトへの変換 #[MapRequestPayload] CreateIssueInput $input, CreateIssueInput::class リクエストボディとして定義した POPO のインスタンスが引数として渡されることが担保される

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } UseCase の In/Out に同じ型を用いる

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } UseCase の In/Out に同じ型を用いる readonly class CreateIssueUseCase { public function execute(CreateIssueInput $input): CreateIssueOutput { // 実装（ここでは割愛） } }

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } Serializer を用いてレスポンスを返す

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } エラーレスポンスの整形

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } エラーレスポンスの整形 readonly class Error { public function __construct( public string $error, ) { } }

EventSubscriber でエラーの整形を行う public function onKernelException(ExceptionEvent $event): void { $exception =
$event->getThrowable(); $isAuthError = $exception instanceof AuthenticationException || $exception instanceof AccessDeniedException || ($exception instanceof HttpException && $exception->getStatusCode() === Response::HTTP_UNAUTHORIZED); if ($isAuthError) { $event->setResponse(new JsonResponse( new Error(error: 'Full authentication is required to access this resource.'), Response::HTTP_UNAUTHORIZED, )); } } https://symfony.com/doc/current/event_dispatcher.html

Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); } リクエストバリデーション

PHP の型定義だけでなく OpenApi Speciﬁcation に基づく検証（format や pattern, minLength 等）も行いたい
リクエストバリデーション

PHP の型定義だけでなく OpenApi Speciﬁcation に基づく検証（format や pattern, minLength 等）も行いたい
→ league/openapi-psr7-validator を利用リクエストバリデーション

league/openapi-psr7-validator https://github.com/thephpleague/openapi-psr7-validator

バリデーション用 EventSubscriber class OpenApiValidationSubscriber implements EventSubscriberInterface { private const string
OPERATION_ADDRESS_ATTRIBUTE = '_openapi_operation_address'; private ServerRequestValidator $requestValidator; private ResponseValidator $responseValidator; private PsrHttpFactory $psrHttpFactory; public function __construct(string $schemaPath) { $builder = new ValidatorBuilder()->fromYamlFile($schemaPath); $this->requestValidator = $builder->getServerRequestValidator(); $this->responseValidator = $builder->getResponseValidator(); $this->psrHttpFactory = new PsrHttpFactory(); } 注）最新の API スキーマがファイル出力されている前提

バリデーション用 EventSubscriber class OpenApiValidationSubscriber implements EventSubscriberInterface { private const string
OPERATION_ADDRESS_ATTRIBUTE = '_openapi_operation_address'; private ServerRequestValidator $requestValidator; private ResponseValidator $responseValidator; private PsrHttpFactory $psrHttpFactory; public function __construct(string $schemaPath) { $builder = new ValidatorBuilder()->fromYamlFile($schemaPath); $this->requestValidator = $builder->getServerRequestValidator(); $this->responseValidator = $builder->getResponseValidator(); $this->psrHttpFactory = new PsrHttpFactory(); } 注）最新の API スキーマがファイル出力されている前提 \Symfony\Bridge\PsrHttpMessage\Factory\PsrHttpFactory

リクエストバリデーション@EventSubscriber public function onKernelRequest(RequestEvent $event): void { if (!$event->isMainRequest()) {
return; } $psrRequest = $this->psrHttpFactory->createRequest($event->getRequest()); try { $operationAddress = $this->requestValidator->validate($psrRequest); } catch (NoPath|NoOperation) { return; } catch (ValidationFailed $e) { $event->setResponse(new JsonResponse( ValidationError::fromValidationFailed($e), Response::HTTP_UNPROCESSABLE_ENTITY, )); return; } $event->getRequest()->attributes->set(self::OPERATION_ADDRESS_ATTRIBUTE, $operationAddress); }

return; } $psrRequest = $this->psrHttpFactory->createRequest($event->getRequest()); try { $operationAddress = $this->requestValidator->validate($psrRequest); } catch (NoPath|NoOperation) { return; } catch (ValidationFailed $e) { $event->setResponse(new JsonResponse( ValidationError::fromValidationFailed($e), Response::HTTP_UNPROCESSABLE_ENTITY, )); return; } $event->getRequest()->attributes->set(self::OPERATION_ADDRESS_ATTRIBUTE, $operationAddress); } PSR-7 準拠のリクエストオブジェクトに変換

「課題作成 API」実装例全体像（再掲） #[Route('', methods: ['POST'])] #[OA\RequestBody( required: true, content:
new OA\JsonContent(ref: new Model(type: CreateIssueInput::class)), )] #[OA\Response( response: 201, description: 'Issue created', content: new OA\JsonContent(ref: new Model(type: CreateIssueOutput::class)), )] #[OA\Response( response: 401, description: 'Unauthorized', content: new OA\JsonContent(ref: new Model(type: Error::class)), )] #[OA\Response( response: 422, description: 'Validation failed', content: new OA\JsonContent(ref: new Model(type: ValidationError::class)), )] public function create( #[CurrentUser] SecurityUser $user, #[MapRequestPayload] CreateIssueInput $input, CreateIssueUseCase $useCase, ): Response { $output = $useCase->execute($input); return JsonResponse::fromJsonString( $this->serializer->serialize($output, 'json'), Response::HTTP_CREATED, ); }

レスポンスバリデーション https://speakerdeck.com/kentaroutakeda/laravel-openapiniyoru-xin-kunai-sukimaqu-dong-kai-fa?slide=69 Laravel OpenAPIによる "辛くない" スキーマ駆動開発 by 武田憲太郎

レスポンスバリデーション public function onKernelRequest(RequestEvent $event): void { if (!$event->isMainRequest()) {

レスポンスバリデーション public function onKernelResponse(ResponseEvent $event): void { if (!$event->isMainRequest()) {
return; } $operationAddress = $event->getRequest()->attributes->get(self::OPERATION_ADDRESS_ATTRIBUTE); if (!$operationAddress instanceof OperationAddress) { return; } $psrResponse = $this->psrHttpFactory->createResponse($event->getResponse()); $this->responseValidator->validate($operationAddress, $psrResponse); }

レスポンスバリデーション public function onKernelResponse(ResponseEvent $event): void { if (!$event->isMainRequest()) {
return; } $operationAddress = $event->getRequest()->attributes->get(self::OPERATION_ADDRESS_ATTRIBUTE); if (!$operationAddress instanceof OperationAddress) { return; } $psrResponse = $this->psrHttpFactory->createResponse($event->getResponse()); $this->responseValidator->validate($operationAddress, $psrResponse); } 例外は捕捉せずに 500 エラーにする

• POPO では nullable と optional を区別できない • 一部のメソッドもプロパティとして解釈されてしまう •
細かい指定をする際の型安全性が低い気をつけるべきポイント

readonly class CreateIssueInput { public function __construct( public ?string $summary,
) { } } POPO では nullable と optional を区別できない CreateIssueInput: properties: summary: type: string nullable: true type: object optional かつ nullable として解釈される

#[OA\Schema(required: ['summary'])] readonly class CreateIssueInput { public function __construct( public
?string $summary, ) { } } POPO では nullable と optional を区別できない CreateIssueInput: required: - summary properties: summary: type: string nullable: true type: object Attributes を明示することで required かつ nullable は表現可能

POPO では nullable と optional を区別できない #[OA\Schema(required: [])] readonly class
CreateIssueInput { public function __construct( #[OA\Property(nullable: false)] public ?string $summary, ) { } } CreateIssueInput: required: - summary properties: summary: type: string type: object optional かつ not null は表現できない（required を上書きできない）

特定キーワード（get, is 等）で始まる public メソッドが対象 • Symfony Serializer の挙動によるもの •
\Nelmio\ApiDocBundle\Attribute\Ignore Attributes を明示的に付与することで対象から外せるメソッドがプロパティとして解釈されてしまう

（再掲）プロパティ単位での Attributes 付与 <?php declare(strict_types=1); namespace App\UseCase\User\GetUserDetail; use OpenApi\Attributes as
OA; use Symfony\Component\Uid\Uuid; readonly class GetUserDetailOutput { public function __construct( public Uuid $id, #[OA\Property(minLength: 5)] public string $name, #[OA\Property(format: 'email')] public string $email, ) { } GetUserDetailOutput: required: - id - name - email properties: id: type: string format: uuid name: type: string minLength: 5 email: type: string format: email type: object

細かい指定をする際の型安全性が低い https://github.com/zircote/swagger-php/blob/master/src/Attributes/Property.php

• swagger-PHP の Attribute の引数は基本的に OpenAPI Speciﬁcation をそのまま持ってきているだけ • 指定可能な引数がすべて
nullable で列挙されており排他な引数のチェックなどは行われない → 最終的には OpenAPI Speciﬁcation を習得する必要がある細かい指定をする際の型安全性が低い

• POPO では nullable と optional を区別できない • 一部のメソッドもプロパティとして解釈されてしまう •
細かい指定をする際の型安全性が低い気をつけるべきポイント（再掲）

ところで

API Platform そして「クモ本」 day2 (3/22) には著者たつきちさんのサイン会もあるよ

＞避けては通れない話題＜

https://api-platform.com/

• Entity やクラスを起点とした CRUD の自動生成 • StateProvider/Processor によるカスタマイズ • JSON-LD、GraphQL
等にも対応 → 実際に現行のプロジェクト開始時に導入検討済み機能は API Platform の方が圧倒的に豊富

• リンケージでは DB 設計の際イミュータブルデータモデルに準拠することが多い • Entity と API リソースが対応しないため、都度カスタマイ
ズが必要になり API Platform の機能を持て余してしまう →「NelmioApiDocBundle でスキーマを生成するだけ」という　シンプルさを優先したそれでも NelmioApiDocBundle を採用した理由

イミュータブルデータモデルに関する参考資料 https://scrapbox.io/kawasima/%E3%82%A4%E3%83%9F%E3%83%A5%E3%83%BC%E3%82%BF%E3% 83%96%E3%83%AB%E3%83%87%E3%83%BC%E3%82%BF%E3%83%A2%E3%83%87%E3%83%AB

参考実装のテーブルと API リソースの対応の例

1. スキーマ駆動開発のメリットと課題 01:00～05:00 2. NelmioApiDocBundle 解説 05:00～08:00 3. API エンドポイント実装例
08:00～17:00 4. 弱み・他の選択肢との比較 17:00～19:30 5. まとめ 19:30～20:00 目次（時間は目安）

スキーマ駆動開発の恩恵に与るための NelmioAPIDocBundle • Controller の Attributes からスキーマを出力できる • refs
に POPO（Plain Old PHP Object）を指定可能 PHP に習熟しているチームほど恩恵が大きい • API エンドポイントの実装に型を直接利用できる • 使い慣れた IDE, 静的解析ツールを利用できるまとめ

Symfony + NelmioApiDocBundle を使った スキーマ駆動開発 / Sc...

Symfony + NelmioApiDocBundle を使った スキーマ駆動開発 / Schema Driven Development with NelmioApiDocBundle

More Decks by Shohei Okada

Other Decks in Programming

Featured

Transcript

Symfony + NelmioApiDocBundle を使ったスキーマ駆動開発 / Sc...

Symfony + NelmioApiDocBundle を使ったスキーマ駆動開発 / Schema Driven Development with NelmioApiDocBundle