Unable to reuse RequestBody definitions via FQCN references

[DanBondarenko]

Version of swagger-php: 4.7.10
Version of PHP: 8.2.7

Hello. I am uncertain as to whether this is a bug or a feature that is not present.

Desired Behaviour

I would like to reference top-level OA\RequestBody definitions from operation definitions using FQCNs (fully qualified class names). The OpenApi 3.0 spec (§ 4.7.10.1) as well as Swagger docs (§ Reusable Bodies) seem to indicate this as a possibility.

Attribute Declarations

#[OA\Post(
    path: '/departments',
    requestBody: new OA\RequestBody(ref: StoreDepartmentRequest::class),
)]
public function store(StoreDepartmentRequest $request): DepartmentResource {}

#[OA\RequestBody(
    request: 'StoreDepartmentRequest',
    content: new OA\JsonContent(
        properties: [
            new OA\Property(property: 'name', type: 'string')
        ]
    )
)]
class StoreDepartmentRequest extends FormRequest {}

Generated OpenAPI YAML

If I understand the OpenAPI spec correctly, the desired OpenAPI document to generate would have the following fragments:

paths:
  /departments:
    post:
      operationId: fa715e92b3f13a22e61601b13cb6921c
      requestBody:
        $ref: '#/components/requestBodies/StoreDepartmentRequest'

components:
  requestBodies:
    StoreDepartmentRequest:
      content:
        application/json:
          schema:
            properties:
              name:
                type: string
            type: object

Actual Behaviour

Inspecting the actual generated OpenAPI YAML, the value under paths.?.post.requestBody.$ref does not seem to be properly processed: instead of a #/components/requestBodies/... URI, the value remains the same as the initial FQCN.

paths:
  /departments:
    post:
      operationId: fa715e92b3f13a22e61601b13cb6921c
      requestBody:
        $ref: App\Http\Requests\StoreDepartmentRequest

Seemingly pertinent parts of codebase

While I am not totally familiar with the swagger-php codebase, I noticed that the following methods seem responsible for the current behaviour:

• \OpenApi\Processors\AugmentRefs::resolveFQCNRefs
• \OpenApi\Analysis::getSchemaForSource

[DerManoMann]

While the spec allows using refs, this library does not (yet) have consistent support for translating FQCN to refs. This works in a few select places but no more, so flagging as enhancement.

Using a ref manually should work.

[stollr]

@DanBondarenko If you are using Symfony as framework you may have a look at the NelmioApiDocBundle which provides this by extending SwaggerPHP.

[momala454]

try type: StoreDepartmentRequest::class instead of ref: StoreDepartmentRequest::class

[andrey-helldar]

Hotfix for me like a:

#[OA\RequestBody(
    request: StoreDepartmentRequest::class, // here
    content: new OA\JsonContent(
        properties: [
            new OA\Property(property: 'name', type: 'string')
        ]
    )
)]
class StoreDepartmentRequest extends FormRequest {}

#[OA\Post(
    path: '/departments',
    requestBody: new OA\RequestBody(ref: '#/components/requestBodies/' . StoreDepartmentRequest::class), // here
)]
public function store(StoreDepartmentRequest $request): DepartmentResource {}