knuckleswtf / knuckleswtf/scribe

Add nullable for ResponseFields in OpenAPI export

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

Description

### Scribe version

5.4.0

### PHP version

8.4

### Laravel version

12.35.0

### Scribe config

```ruby
n/a
```

### What happened?

Currently the OpenAPI generation ignores the `nullable` parameter for ResponseFields. (which is valid for OpenAPI 3.0)

After digging the sources a naive "fix" would be:

1. Add `public $nullable;` to `camel/Extraction/ResponseField.php`
2. Under `generateSchemaForResponseValue()` in `src/Writing/OpenApiSpecGenerators/BaseGenerator.php` add

L568
```
$this->setDescription($schema, $endpoint, $path);

//either it's explicitly nullable or the value is null (don't know if this is legit?)
if ((isset($endpoint->responseFields[$path]->nullable) && $endpoint->responseFields[$path]->nullable) || $value === null) {
$schema['nullable'] = true;
}
```

However I also stumbled over you comment here https://scribe.knuckles.wtf/laravel/migrating#more-configurable-openapi-generation - would it be possible and do you recommend to use this approach to add the nullable parameter to responseField? Or do you prefer an enhancement like the above code?

### 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 camel/Extraction/ResponseField.php and generateSchemaForResponseValue() in src/Writing/OpenApiSpecGenerators/BaseGenerator.php. Read the linked configurable OpenAPI generation guidance before choosing how nullable should be exposed. Done means ResponseFields' nullable setting is represented in the generated OpenAPI schema, including the documented null-value behavior.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.