shortName, Description, and OpenAPI Metadata

The Swagger UI from chapter 6 currently shows RATHER technical labels – shortName and description at the resource level make the generated documentation MORE READABLE, without affecting the code itself.

Setting shortName

api/src/Entity/Project.php

#[ApiResource(
    shortName: 'Venture',
    description: 'An initiative in the task manager that bundles several tasks.',
    operations: [
        // ...
    ]
)]

shortName does NOT affect the API path (it stays /api/projects), ONLY the label that appears in Swagger UI, the OpenAPI specification, and the JSON-LD @type fields – here "@type": "Venture" would appear in API responses instead of "@type": "Project".

Achtung: For OUR project we stick with the default English names (Project, Tag), since MIXED naming would only cause confusion once React comes into play (block 9) – this chapter shows the POSSIBILITY, not a recommendation for this project.

Description per operation combined with shortName

new Post(description: 'Creates a new project.'),
new Delete(description: 'Deletes a project IRREVERSIBLY, including all its tasks.'),

Operation descriptions and the resource-level description COMPLEMENT each other in Swagger UI: the resource description appears AT THE TOP of the relevant section, the operation description NEXT TO its own row.

Marking an operation as deprecated

new Get(
    deprecated: true,
    description: 'Deprecated, please use /api/projects/{id}/details instead.'
),

deprecated: true shows a CLEAR visual signal in Swagger UI (strikethrough/grayed out), WITHOUT actually disabling the endpoint – useful for a GRADUAL transition to a new endpoint instead of removing an existing one abruptly.

Tipp: ALL parameters shown here are pure METADATA for documentation/tooling – they change NEITHER the database NOR the actual access logic, EXACTLY like uriTemplate in chapter 13.