knuckleswtf / knuckleswtf/scribe
Add nullable for ResponseFields in OpenAPI export
- 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
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