api-platform / api-platform/schema-generator

Arazzo spec

Ouverte
#443 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
PHP
Étoiles
474
Forks
107
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

**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

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.