Required Fields In OpenAPI Schema

[atoff]

Scribe version

4.19.0

Your question

Hello,

Really love this package by the way! I've been having some issues recently where I have been trying to use the OpenAPI schema generated by scribe for codegeneration clientside. The main issue is that I can't seem to find a way to make it generate a schema that respects that response fields are required in the output (i.e. not nullable/undefined). Essentially, I have this resource

class TelemetryResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @responseField latitude float required Telemetry latitude
     * @responseField longitude float required Telemetry Longitude
     * @responseField heading int required Magnetic Heading
     * @responseField source string Data source Example: VATSIM
     * @responseField next_update string DateTime of next expected data update
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'latitude' => $this->latitude,
            'longitude' => $this->longitude,
            'heading' => $this->heading,
            'source' => $this->source ? $this->source->description : null,
            'next_update' => $this->expectedNextUpdate(),
        ];
    }
}

being returned from this endpoint

/**
     * User Telemetry
     *
     * Access OAuth user's flight simulator telemetry, if any is available. Requies the oauth:telemetry:view scope
     *
     * @apiResource App\Http\Resources\User\TelemetryResource
     *
     * @response status=404 scenario="no telemetry available" {"message": "No telemetry currently available for this user"}
     *
     * @apiResourceModel App\Models\User\Telemetry
     */
    public function telemetry(Request $request)
    {
        $telemetry = $request->user()->activeTelemetry();

        return $telemetry ? TelemetryResource::make($request->user()->activeTelemetry()) : abort(404, 'No telemetry currently available for this user');
    }

This gives a nominal response type that looks like:

"data": {
   "latitude": 82.4,
   "longitude": 126.7,
   ...
}

However, inside the OpenAPI schema generated by Scribe, the inner properties of the data object does not include the necessary required entry.

Current OpenAPI Schema

      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    latitude: 84.168012
                    longitude: 126.256313
                    heading: 186
                    source: 'XYZ'
                    next_update: '2023-05-07T15:41:38.000000Z'
                properties:
                  data:
                    type: object
                    properties:
                      latitude:
                        type: number
                        example: 84.168012
                      longitude:
                        type: number
                        example: 126.256313
                        description: 'required Longitude'
                      heading:
                        type: integer
                        example: 186
                      source:
                        type: string
                        example: 'XYZ'
                      next_update:
                        type: string
                        example: '2023-05-07T15:41:38.000000Z'
       ....

Expected OpenAPI Schema

...
              schema:
                type: object
                example:
                  data:
                    latitude: 84.168012
                    longitude: 126.256313
                    heading: 186
                    source: 'XYZ'
                    next_update: '2023-05-07T15:41:38.000000Z'
                properties:
                  data:
                    type: object
                    properties:
                      latitude:
                        type: number
                        example: 84.168012
                      longitude:
                        type: number
                        example: 126.256313
                      heading:
                        type: integer
                        example: 186
                      source:
                        type: string
                        example: 'XYZ'
                      next_update:
                        type: string
                        example: '2023-05-07T15:41:38.000000Z'
                    required:
                      - latitude
                      - longitude
                      - heading
...

Am I missing something or is this not possible? I've trawled through the docs and can't seem to find a way to do this. Thanks!

Docs

• [X] I've checked the docs, the troubleshooting guide, and existing issues, but I didn't find a solution

[shalvah]

Oof, just seeing this... it's not currently supported for responses. I'll put this on the radar, though.

[yannick-softwerft]

@shalvah Are there any news if this is getting integrated soon? I think its pretty mandatory feature for generating a typescript API client.

[shalvah]

Sorry, I've not had a chance to look at this. Quite busy these days.

[shalvah]

I recommend sending in a PR if it's really needed. It isn't complex to implement, and I'll gladly review and merge.

[yannick-softwerft]

@shalvah I added a PR: https://github.com/knuckleswtf/scribe/pull/814