api-platform / api-platform/schema-generator

Arazzo spec

Abierto
#443 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
PHP
Estrellas
474
Forks
107
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

**Description**

Would you consider supporting Arazzo specification as an input source to generate API Platform operation stubs (State Processors, custom operations) ?

I'm exploring the idea of using the [Arazzo Specification](https://github.com/OAI/Arazzo-Specification) (OAI, v1.0.1) as an input source to generate **custom operation stubs** for API Platform — State Processors, Input DTOs, and `#[Post]`/`#[Patch]` attribute additions to existing entities.

I'd love to know if this fits the project's vision or should live in a separate package.

Related issue I noticed: #440

## Context

Arazzo is the OAI specification for describing multi-step API workflows. Where OpenAPI describes *what* endpoints exist, Arazzo describes *how a consumer orchestrates calls* across those endpoints — including input/output chaining, success criteria, and error handling.

The key insight: **an Arazzo file contains enough information to infer which API Platform custom operations are missing**, and what their input shapes look like.

## Proposed workflow

```bash
vendor/bin/schema generate user-onboarding.arazzo.yaml
```

The command would:
1. Parse the Arazzo file
2. Load the current OpenAPI spec generated by API Platform
3. **Diff**: detect `operationId`s referenced in Arazzo but absent from OpenAPI
4. Generate the corresponding PHP stubs

## Example

### Input: `user-onboarding.arazzo.yaml`

```yaml
arazzo: 1.0.0
info:
title: User Onboarding
version: 1.0.0
sourceDescriptions:
- name: api
url: ./api/openapi.yaml
type: openapi

workflows:
- workflowId: user_onboarding
steps:
- stepId: register
operationId: api_users_post_collection
successCriteria:
- condition: $statusCode == 201
outputs:
userId: $response.body#/id

- stepId: verify_email
operationId: api_users_verify_post
parameters:
- name: id
in: path
value: $steps.register.outputs.userId
requestBody:
payload:
token: { type: string }
successCriteria:
- condition: $statusCode == 200

- stepId: complete_profile
operationId: api_users_complete_profile_patch
parameters:
- name: id
in: path
value: $steps.register.outputs.userId
requestBody:
payload:
bio: { type: string }
avatarUrl: { type: string, format: uri }
successCriteria:
- condition: $statusCode == 200
```

### Expected command output

```
✔ api_users_post_collection → already exists in OpenAPI, skipped
✘ api_users_verify_post → generating...
→ src/Dto/Input/UserVerifyInput.php
→ src/State/UserVerifyProcessor.php
→ (adds #[Post] operation to src/Entity/User.php)
✘ api_users_complete_profile_patch → generating...
→ src/Dto/Input/UserCompleteProfileInput.php
→ src/State/UserCompleteProfileProcessor.php
→ (adds #[Patch] operation to src/Entity/User.php)

2 operation stub(s) generated.
```

### Generated: `src/Dto/Input/UserVerifyInput.php`

```php

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.