knuckleswtf / knuckleswtf/scribe
How to mark a property of response as nullable and / or required when using `ResponseFromApiResource` attribute class?
- Dominant language
- PHP
- Stars
- 2.3k
- Forks
- 357
- PR merge metrics
- No merged PRs in 30d
Description
- [x] I've read the [documentation](https://scribe.knuckles.wtf/laravel) and I can't find details on how to achieve this.
My team heavily rely on openapi generator: https://github.com/OpenAPITools/openapi-generator , to generate a type-safe interface from openapi documentation for our frontend typescript project to call API.
For request parameter, this library did a really good job on generate sound request interface. But for response, I struggle on creating a reliable response interface with `#[ResponseFromApiResource]` Attribute.
The issue I am facing is that, when converting a open api endpoint response to interface, all openapi generator tools I use will mark object properties as optional, if it's not marked as `required`. For example, for a response with structure like this:
```
type: object
properties:
cost_ratio:
type: number
example: 1.2
ms_team_webhook_url:
type: string
```
would end up generate an interface in typescript like this:
```
interface TestObject {
cost_ratio?: number;
ms_team_webhook_url?: string;
}
```
The question-mark indicates that the field is possibly `undefined`, which is not the case for most of our API response. so we need to update the schema like this:
```
type: object
required:
- cost_ratio
- ms_team_webhook_url
properties:
cost_ratio:
type: number
ms_team_webhook_url:
type: string
```
It's similar for `nullable` fields.
I don't expect this library to automatically add these `required` attributes for me, as I know that's really hard to determine if a field is nullable / required merely by reading the resource file, after all it's not a type-hinted file like a typescript interface. But it seems that there's no way to add it manually too. Did I miss something or it's currently impossible to do so?
Contributor guide
Research direction
Start with the ResponseFromApiResource attribute and the linked Scribe documentation, then trace how it produces the OpenAPI response schema. Done means a documented way to mark response properties as required or nullable manually, with the generated schema preserving those declarations for OpenAPI Generator.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- laravel, openapi, php
- Domain
- api
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100