knuckleswtf / knuckleswtf/scribe

Empty example tag in OpenAPI spec leads to missing request body in documentation.

Open
#904 2 comments 0 reactions 0 assignees View on GitHub
bug validated
Dominant language
PHP
Stars
2.3k
Forks
357
PR merge metrics
No merged PRs in 30d

Description

### Scribe version

4.36.0

### Your question

One of our endpoints receives an array of objects which is wrapped in a data wrapper (see example).
We validate the input with a Laravel Form Request and provide more meaningful description and examples via `bodyParameter()` method (see below). This leads to an almost perfect OpenAPI Yaml, which we use with the Scalar theme.

**Problem:** The `data` property which holds all child objects has an empty array as example value in the OpenAPI spec. If we would remove the `example: []` property from the specification, the provided body parameters appear in the example request.

![Screenshot 2024-10-24 at 11 05 10](https://github.com/user-attachments/assets/66792146-216e-473e-b1a3-8cde750a38ac)

**Steps I tried:**
- I already tried to understand the [ParsesValidationRules.php](https://github.com/knuckleswtf/scribe/blob/4.36.0/src/Extracting/ParsesValidationRules.php#L691) logic which should generate the correct example string, but I don't find an issue.
- I already tried to understand the [OpenAPISpecWriter.php](https://github.com/knuckleswtf/scribe/blob/4.36.0/src/Writing/OpenAPISpecWriter.php#L300) logic which writes the example.

```JSON
{
"meta": {
"driver": "AryaSvitkona",
"hasLicense": 1
},
"data":
[
{
"id": "Foobar123",
"start": "Europe",
"end": "Canada",
"duration_h": 100
}
]
}
```

```PHP
// Rules
public function rules(): array {
return [
'meta.driver' => 'required|string',
'meta.hasLicense' => 'required|boolean',
'data' => 'required|array',
'data.*.id' => 'required|string',
'data.*.start' => 'required|string',
'data.*.end' => 'required|string',
'data.*.duration_h' => 'int',
];
}

// Description
public function bodyParameters(): array {
return [
'data.*.id' => [
'description' => 'Id which is generated by your chief.',
'example' => 'Foobar1313',
],
'data.*.start' => [
'description' => 'Country where you start',
'example' => 'Spain',
],
'data.*.end' => [
'description' => 'Country where you arrive.',
'example' => 'Sweden',
],
'data.*.duration_h' => [
'description' => 'Duration in hours.',
'example' => 11,
],
];
}
```

P.S. Kudos to you for providing this awesome dependency! Thank you!

### Docs

- [X] I've checked [the docs](https://scribe.knuckles.wtf/laravel), the [troubleshooting guide](https://scribe.knuckles.wtf/laravel/troubleshooting), and [existing issues](https://github.com/knuckleswtf/scribe/issues?q=is%3Aissue+), but I didn't find a solution

Contributor guide

Open the contributing guide

Research direction

Start with the example Laravel validation rules and bodyParameters() data, then trace array examples in src/Extracting/ParsesValidationRules.php around line 691 and example writing in src/Writing/OpenAPISpecWriter.php around line 300. Reproduce the generated OpenAPI YAML and confirm that the data property no longer has an empty example that hides the nested body parameters in the request example.

Written by the indexing model from the issue text.

Assessment

Tech stack
laravel, openapi, php
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.