knuckleswtf / knuckleswtf/scribe

Try-it-out fails if ```file``` field is present but with ```No-example```

Open
#975 1 comment 0 reactions 0 assignees View on GitHub
bug
Dominant language
PHP
Stars
2.3k
Forks
357
PR merge metrics
No merged PRs in 30d

Description

### Scribe version

5.1.0

### PHP version

8.3.6

### Laravel version

11.44.2

### Scribe config

```ruby
try_it_out.use_csrf => true
openapi.enabled => false
```

### What happened?

TL;DR: Endpoints using ```file``` fields do not work properly when trying-it-out unless they have an example attached.

It is expected that an Endpoint receiving a file (via POST) will have its Content-type changed from ```application/json``` to ```multipart/formdata``` "automagically" by the try-it-out code embedded in the documentation, if there is at least one field of the ```file``` type.

However, if the field is documented in the Controller's method documentation header and the ```No-example``` hint is added, this does not happen, the try-it-out code simply does not detect the ```file``` field for the purpose of changing the ```Content-Type``` and doing the proper data encoding. The ```file``` field still is present and the file is still selectable, but of course is never received by the endpoint.

For example, if the endpoint has the following like in the documentation, the try-it-out will not work.

```
* @bodyParam foto file Foto de Perfil do Projeto, opcional. No-example
```

![Image](https://github.com/user-attachments/assets/9944db5e-5061-45c1-9820-67a60d565ed9)

However, if I change the like to:

```
* @bodyParam foto file Foto de Perfil do Projeto, opcional.
```
(note the missing ```No-example```)

It will work as intended:

![Image](https://github.com/user-attachments/assets/d3d2d664-6d17-4f17-bfdd-19f0c8159008)

Below, snippet of the request as captured by Firefox:

![Image](https://github.com/user-attachments/assets/734812e7-5285-4141-b414-7d805142dd6f)

If there isn't the ```No-example``` hint, and I do not select any file, the ```file``` field is properly ignored and not sent, so this becomes just an annoyance and not a show stopper anymore after this was discovered.

Thanks in advance.

### 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 by reproducing the try-it-out request for an endpoint documented with an @bodyParam file field and the No-example hint. Trace how the embedded try-it-out code detects file fields and selects multipart/form-data; done means the request uses the correct encoding even when no example is attached, while preserving the existing behavior when no file is selected.

Written by the indexing model from the issue text.

Assessment

Tech stack
laravel, 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.