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

[AryaSvitkona]

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 logic which should generate the correct example string, but I don't find an issue.
• I already tried to understand the OpenAPISpecWriter.php logic which writes the example.

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

// 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, the troubleshooting guide, and existing issues, but I didn't find a solution

[shalvah]

Ah, so a preferred resolution would be: for an array of items, rather than generate an empty array as example, omit the example if not sure?

If you're looking for a pointer, I think the cause is in generateFieldData. https://github.com/knuckleswtf/scribe/blob/a6aee1d56177e2f541c07f1a02a7a9e795d1facd/src/Writing/OpenAPISpecWriter.php#L517

It may be as easy as adding a check to remove the example:

if(Utils::isArrayType($baseType) && is_empty($field->example)) {
  unset($fieldData['example']);
}

But I haven't verified. I don't know when I'll get to this, so I encourage you to give it a try.

[AryaSvitkona]

Thanks! I already thought about to contribute this small improvement, since I now have the confirmation, that we didn't do anything wrong.