api-platform / api-platform/schema-generator

Arazzo spec

Đang mở
#443 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
PHP
Star
474
Fork
107
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.