knuckleswtf / knuckleswtf/scribe
Empty example tag in OpenAPI spec leads to missing request body in documentation.
- 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.

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