Feature | Extend Swagger Coverage for controller OAuth2OrganizationsApiController

[matiasperrone-exo]

Task:

Ref: https://app.clickup.com/t/86b6wkgp2

[caseylocker]

There is at least one breaking error here. Description follows:

Line 56-61: Invalid Response References
Error: References #/components/responses/400, etc. which don't exist in the OpenAPI spec
Fix: Replace with inline descriptions:
new OA\Response(response: 400, description: "Bad Request"),
new OA\Response(response: 401, description: "Unauthorized"),
new OA\Response(response: 403, description: "Forbidden"),
new OA\Response(response: 412, description: "Precondition Failed - Validation Error"),
new OA\Response(response: 422, description: "Unprocessable Entity"),
new OA\Response(response: 500, description: "Server Error"),

Line 45: Inconsistent Tag Naming. This is the same issue that we've seen before. Just make it Title Case.
Current: tags: ['organizations'] (lowercase)
Expected: tags: ['Organizations'] (Title Case - matches line 88 and project convention)

Line 44: I don't find 'oauth2_security_scope' defined anywhere.
security: [['oauth2_security_scope' => ...]]

[matiasperrone-exo]

@caseylocker @smarcet the security scope was updated with the right value.

[caseylocker]

@matiasperrone
IGNORE THIS - Name space issue: namespace App\Swagger\Schemas; needs to be namespace App\Swagger\Security;
I didn't take into account pr 385

In OAuth2OrganizationsApiController.php: the POST endpoint is missing operationId (but GET has it). It's also missing a description.

In app/Swagger/schemas.php you missing the type: 'object' declaration in the allOf for PaginatedOrganizationsResponse.

[caseylocker]

@matiasperrone-exo there's a capitalization issue with the namespace in OrganizationsAuthSchema.php
// Current (WRONG)
namespace App\Swagger\Schemas; // Capital 'S'
// Required (CORRECT)
namespace App\Swagger\schemas; // Lowercase 's'

Also needs and operationId.
#[OA\Post(
path: '/api/v1/organizations',
operationId: 'createOrganization', // ← ADD THIS
summary: 'Creates a new organization',
// ...
)]

Once those 2 items are fixed it should be good to go.

[caseylocker]

Good to go.

[smarcet]

LGTM