Swagger-PHP

Appearance

Spec Attribute Reference ​

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR 😉

Spec attributes are typed PHP attributes in the OpenApi\Spec namespace — the foundation of the spec-attributes pipeline (--mode spec or --mode hybrid).

They are data containers with no serialization logic; augmenters fill in derived values. Relationships are declared via merge() (what sibling an attribute composes into on the same reflector) and contained() (what parent types can absorb this attribute from inner reflector levels). The Assembler resolves nesting, and Augmenters enrich the collected specification before compilation.

Typed subclasses (e.g. Operation\Get, Parameter\Path, Flow\AuthorizationCode) pre-fill common fields to reduce boilerplate — the base class can always be used directly.

Spec Attributes ​

Attachable ​

Base class for custom attributes.

By default not allowed to contain other attributes, but can be inline nested into any other attribute (including itself).

Components ​

Container for reusable component definitions.

Place on a class to declare standalone components that go into the components section of the OpenAPI document. The Components attribute itself is not emitted — its children are promoted to their respective Specification buckets.

The primary use case is for DTOs that are NOT roots and therefore cannot be declared at class level on their own: Parameter, Header, Link, and Example. Other types (Schema, PathItem, SecurityScheme, named Response/RequestBody) are already roots and can be declared directly on a class without needing a Components wrapper.

#[Components] class SharedComponents { #[Parameter(parameter: 'tenant_id', name: 'tenant_id', in: 'path', schema: new Schema(type: 'string'))] public string $tenantId;

  #[Header(header: 'X-Rate-Limit', schema: new Schema(type: 'integer'))]
  public string $rateLimit;

  #[Example(example: 'dog', summary: 'A dog', value: ['name' => 'Fido'])]
  public string $dogExample;

}

Nested elements ​

Security\Scheme, Security\Scheme\ApiKey, Security\Scheme\Http, Security\Scheme\MutualTls, Security\Scheme\OAuth2, Security\Scheme\OpenIdConnect

Parameters ​

schemas : list<Schema>

No details available.

parameters : list<Parameter>

No details available.

responses : list<Response>

No details available.

requestBodies : list<RequestBody>

No details available.

headers : list<Header>

No details available.

securitySchemes : list<Security\Scheme>

No details available.

links : list<Link>

No details available.

examples : list<Example>

No details available.

Contact ​

Contact information for the exposed API.

Allowed in ​

Info

Parameters ​

name : string|null

The identifying name of the contact person/organization

url : string|null

A URL pointing to the contact information

email : string|null

The email address of the contact person/organization

Reference ​

Discriminator ​

Aids in serialization, deserialization, and validation when request bodies or responses can be one of several schemas (used with oneOf, anyOf, allOf).

Allowed in ​

Schema

Parameters ​

propertyName : string|null

The name of the property in the payload that distinguishes types

mapping : array<string,string>|null

Maps payload values to schema names or references

Reference ​

Encoding ​

Describes the encoding for a single property in a media type.

Allowed in ​

MediaType

Parameters ​

encoding : string|null

The property name this encoding applies to

contentType : string|null

The Content-Type for encoding a specific property

headers : list<Header>|null

Additional headers for multipart media types

style : string|ParameterStyle|null

How the property value is serialized

explode : bool|null

Whether arrays/objects generate separate parameters

allowReserved : bool|null

Whether reserved characters are allowed without encoding

Reference ​

Example ​

Describes an example value for a parameter, media type, or schema.

Allowed in ​

MediaType, Parameter, Header

Parameters ​

example : string|null

Reusable example identifier (component key)

summary : string|null

Short description of the example

description : string|null

Long description of the example (CommonMark syntax)

value : mixed

Embedded literal example value

externalValue : string|null

A URI pointing to the literal example

ref : string|null

A JSON Reference to a reusable example

Reference ​

ExternalDocumentation ​

Allows referencing an external resource for extended documentation.

Allowed in ​

Tag

Parameters ​

url : string|null

The URL for the target documentation

description : string|null

A description of the target documentation (CommonMark syntax)

Reference ​

Flow ​

Configuration details for a supported OAuth2 flow.

Typed subtypes pre-fill the flow type:

  • OA\Flow\Implicit - implicit grant (authorizationUrl required)

  • OA\Flow\Password - resource owner password credentials (tokenUrl required)

  • OA\Flow\ClientCredentials - client credentials grant (tokenUrl required)

  • OA\Flow\AuthorizationCode - authorization code grant (authorizationUrl + tokenUrl required)

    #[OA\Security\Scheme\OAuth2(securityScheme: 'oauth2', flows: [ new OA\Flow\AuthorizationCode( authorizationUrl: 'https://example.com/oauth/authorize', tokenUrl: 'https://example.com/oauth/token', scopes: ['read:pets' => 'Read pets', 'write:pets' => 'Write pets'], ), ])]

Produces: components: securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read:pets: Read pets write:pets: Write pets

Allowed in ​

Security\Scheme

Parameters ​

flow : string|FlowType|null

The OAuth2 flow type (implicit, password, clientCredentials, authorizationCode)

authorizationUrl : string|null

The authorization URL for this flow

tokenUrl : string|null

The token URL for this flow

refreshUrl : string|null

The URL for obtaining refresh tokens

scopes : array<string,string>|null

The available scopes for the OAuth2 security scheme

Reference ​

Flow\AuthorizationCode ​

Configuration for the OAuth2 Authorization Code flow.

Allowed in ​

Security\Scheme

Parameters ​

authorizationUrl : string|null

No details available.

tokenUrl : string|null

No details available.

refreshUrl : string|null

No details available.

scopes : array<string,string>|null

No details available.

Reference ​

Flow\ClientCredentials ​

Configuration for the OAuth2 Client Credentials flow.

Allowed in ​

Security\Scheme

Parameters ​

tokenUrl : string|null

No details available.

refreshUrl : string|null

No details available.

scopes : array<string,string>|null

No details available.

Reference ​

Flow\Implicit ​

Configuration for the OAuth2 Implicit flow.

Allowed in ​

Security\Scheme

Parameters ​

authorizationUrl : string|null

No details available.

refreshUrl : string|null

No details available.

scopes : array<string,string>|null

No details available.

Reference ​

Flow\Password ​

Configuration for the OAuth2 Resource Owner Password flow.

Allowed in ​

Security\Scheme

Parameters ​

tokenUrl : string|null

No details available.

refreshUrl : string|null

No details available.

scopes : array<string,string>|null

No details available.

Reference ​

Describes a single HTTP header.

Allowed in ​

Response

Nested elements ​

Example, MediaType, MediaType\Json, MediaType\Xml

Parameters ​

header : string|null

The header name (component key)

description : string|null

A brief description of the header (CommonMark syntax)

required : bool|null

Whether the header is mandatory

deprecated : bool|null

Whether the header is deprecated

ref : string|Schema\Ref|null

A JSON Reference to a reusable header

style : string|ParameterStyle|null

How the header value is serialized

explode : bool|null

Whether arrays/objects generate separate parameters

schema : Schema|null

The schema defining the type for the header

example : mixed

Example of the header's value

examples : list<Example>|null

Examples of the header's value

content : MediaType|list<MediaType>|null

Content-type based header serialization

Reference ​

Info ​

Metadata about the API.

Nested elements ​

Contact, License

Parameters ​

title : string|null

The title of the API

description : string|null

A description of the API (CommonMark syntax)

termsOfService : string|null

A URL to the Terms of Service for the API

version : string|null

The version of the API document

contact : Contact|null

Contact information for the API

license : License|null

License information for the API

summary : string|null

A short summary of the API

Reference ​

License ​

License information for the exposed API.

Allowed in ​

Info

Parameters ​

name : string|null

The license name used for the API

identifier : string|null

An SPDX license expression for the API

url : string|null

A URL to the license used for the API

Reference ​

Describes a possible design-time link for a response.

Allowed in ​

Response

Parameters ​

link : string|null

Reusable link identifier (component key)

operationRef : string|null

A relative or absolute URI reference to a linked operation

operationId : string|null

The name of an existing operation (mutually exclusive with operationRef)

parameters : array<string,mixed>|null

Values to pass to the linked operation's parameters

requestBody : mixed

A value to use as the request body for the linked operation

description : string|null

A description of the link (CommonMark syntax)

ref : string|null

A JSON Reference to a reusable link

server : Server|null

A server object to be used by the target operation

Reference ​

MediaType ​

Describes the content payload for a specific media type.

Allowed in ​

Response, RequestBody, Parameter, Header

Nested elements ​

Encoding, Example

Parameters ​

mediaType : string|null

The media type identifier (e.g. 'application/json')

schema : Schema|null

The schema defining the content

example : mixed

Example of the media type content

examples : list<Example>|null

Examples of the media type content

encoding : list<Encoding>|array<string,Encoding>|null

Encoding information for specific properties

Reference ​

MediaType\Json ​

Describes the content payload for application/json.

A shortcut version of OA\MediaType with some of the more common OA\Schema properties added.

  • mediaType is set to application/json by default.
  • ref, type, items, properties and required may be used and will be expanded into a nested OA\Schema automatically.
  • If schema is explicitly set, the custom OA\Schema properties will be ignored.

Allows to shorten this:

#[OA\Response(response: 200, content: [ new OA\MediaType(mediaType: 'application/json', schema: new OA\Schema(type: 'array', items: new OA\Schema(ref: Pet::class))), ])]

to this:

#[OA\Response(response: 200, content: [new OA\MediaType\Json(type: 'array', items: new OA\Schema(ref: Pet::class))])]

The Shortcuts augmenter expands the schema properties into a nested OA\Schema automatically.

Allowed in ​

Response, RequestBody, Parameter, Header

Parameters ​

ref : string|null

A JSON Reference to a reusable schema

type : string|list<string>|null

The value type(s) (string, number, integer, boolean, array, object, null)

items : Schema|string|null

Schema for array items

properties : list<Property>|null

Object property definitions

required : list<string>|null

List of required property names

schema : Schema|null

The schema defining the content

example : mixed

Example of the media type content

examples : list<OA\Example>|null

Examples of the media type content

encoding : list<OA\Encoding>|array<string,OA\Encoding>|null

Encoding information for specific properties

Reference ​

MediaType\Xml ​

Describes the content payload for application/xml.

A shortcut version of OA\MediaType with some of the more common OA\Schema properties added.

  • mediaType is set to application/xml by default.
  • ref, type, items, properties and required may be used and will be expanded into a nested OA\Schema automatically.
  • If schema is explicitly set, the custom OA\Schema properties will be ignored.

Allows to shorten this:

#[OA\Response(response: 200, content: [ new OA\MediaType(mediaType: 'application/xml', schema: new OA\Schema(type: 'array', items: new OA\Schema(ref: Pet::class))), ])]

to this:

#[OA\Response(response: 200, content: [new OA\MediaType\Xml(type: 'array', items: new OA\Schema(ref: Pet::class))])]

The Shortcuts augmenter expands the schema properties into a nested OA\Schema automatically.

Allowed in ​

Response, RequestBody, Parameter, Header

Parameters ​

ref : string|null

A JSON Reference to a reusable schema

type : string|list<string>|null

The value type(s) (string, number, integer, boolean, array, object, null)

items : Schema|string|null

Schema for array items

properties : list<Property>|null

Object property definitions

required : list<string>|null

List of required property names

schema : Schema|null

The schema defining the content

example : mixed

Example of the media type content

examples : list<OA\Example>|null

Examples of the media type content

encoding : list<OA\Encoding>|array<string,OA\Encoding>|null

Encoding information for specific properties

Reference ​

OpenApi ​

The root element of an OpenAPI definition.

Nested elements ​

Security\Requirement

Parameters ​

version : string|null

The OpenAPI specification version (e.g. '3.1.0')

security : list<Security\Requirement>|null

Default security requirements for the API

Reference ​

Operation ​

Describes a single API operation on a path.

Typed subclasses pre-fill the HTTP method — use them instead of specifying method manually:

#[OA\Operation\Get(path: '/pets/{id}', responses: [ new OA\Response(response: 200, description: 'A pet', content: [ new OA\MediaType(schema: new OA\Schema(ref: Pet::class)), ]), ])] public function show(int $id) {}

Produces: paths: /pets/{id}: get: operationId: show responses: '200': description: A pet content: application/json: schema: $ref: '#/components/schemas/Pet'

For webhooks, use webhook instead of path:

#[OA\Operation\Post(webhook: 'petAdopted', responses: [...])]

Nested elements ​

Parameter, Parameter\Cookie, Parameter\Header, Parameter\Path, Parameter\Query, RequestBody, Response, Security\Requirement, Server

Parameters ​

path : string|null

The URL path for the operation

webhook : string|null

The webhook name (mutually exclusive with path)

method : string|HttpMethod|null

The HTTP method (get, post, put, delete, etc.)

operationId : string|null

Unique identifier for the operation

summary : string|null

A short summary of what the operation does

description : string|null

A verbose explanation of the operation (CommonMark syntax)

tags : list<string>|null

Tags for API documentation grouping

parameters : list<Parameter>|null

Parameters applicable to this operation

requestBody : RequestBody|null

The request body applicable to this operation

responses : list<Response>|null

The list of possible responses

callbacks : array<string,mixed>|null

Possible out-of-band callbacks related to the operation

deprecated : bool|null

Whether the operation is deprecated

security : list<Security\Requirement>|null

Security mechanisms that can be used for this operation

servers : list<Server>|null

Alternative servers for this operation

externalDocs : ExternalDocumentation|null

Additional external documentation

Reference ​

Operation\Delete ​

Shorthand for an HTTP DELETE operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

requestBody : OpenApi\Spec\RequestBody|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Get ​

Shorthand for an HTTP GET operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<Parameter>|null

No details available.

responses : list<Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Head ​

Shorthand for an HTTP HEAD operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Options ​

Shorthand for an HTTP OPTIONS operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Patch ​

Shorthand for an HTTP PATCH operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

requestBody : OpenApi\Spec\RequestBody|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Post ​

Shorthand for an HTTP POST operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

requestBody : OpenApi\Spec\RequestBody|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Put ​

Shorthand for an HTTP PUT operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

requestBody : OpenApi\Spec\RequestBody|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Operation\Trace ​

Shorthand for an HTTP TRACE operation.

Parameters ​

path : string|null

No details available.

webhook : string|null

No details available.

operationId : string|null

No details available.

summary : string|null

No details available.

description : string|null

No details available.

tags : list<string>|null

No details available.

parameters : list<OA\Parameter>|null

No details available.

responses : list<OA\Response>|null

No details available.

callbacks : array<string,mixed>|null

No details available.

deprecated : bool|null

No details available.

security : list<OA\Security\Requirement>|null

No details available.

servers : list<OA\Server>|null

No details available.

externalDocs : OpenApi\Spec\ExternalDocumentation|null

No details available.

Reference ​

Parameter ​

Describes a single operation parameter.

Typed subtypes pre-fill in (and required for path):

  • OA\Parameter\Path - path parameters (in: path, required: true)
  • OA\Parameter\Query - query string parameters (in: query)
  • OA\Parameter\Header - header parameters (in: header)
  • OA\Parameter\Cookie - cookie parameters (in: cookie)

Inline on an operation:

#[OA\Operation\Get(path: '/pets', parameters: [ new OA\Parameter\Query(name: 'status', schema: new OA\Schema(type: 'string', enum: ['active', 'sold'])), ])]

Or as a reusable component (set parameter for the component key):

#[OA\Parameter\Path(parameter: 'petId', name: 'id', schema: new OA\Schema(type: 'integer'))]

Produces: components: parameters: petId: name: id in: path required: true schema: type: integer

Allowed in ​

Operation, PathItem

Nested elements ​

Example, MediaType, MediaType\Json, MediaType\Xml

Parameters ​

parameter : string|null

Reusable parameter identifier (component key)

name : string|null

The name of the parameter

in : string|ParameterIn|null

The location of the parameter (query, header, path, cookie)

description : string|null

A brief description of the parameter (CommonMark syntax)

required : bool|null

Whether the parameter is mandatory

deprecated : bool|null

Whether the parameter is deprecated

allowEmptyValue : bool|null

Whether empty-valued parameters are allowed

ref : string|Schema\Ref|null

A JSON Reference to a reusable parameter

style : string|ParameterStyle|null

How the parameter value is serialized

explode : bool|null

Whether arrays/objects generate separate parameters

allowReserved : bool|null

Whether reserved characters are allowed without encoding

schema : Schema|null

The schema defining the type for the parameter

example : mixed

Example of the parameter's value

examples : list<Example>|null

Examples of the parameter's value

content : MediaType|list<MediaType>|null

Content-type based parameter serialization

Reference ​

A parameter passed via an HTTP cookie.

Allowed in ​

Operation, PathItem

Parameters ​

parameter : string|null

No details available.

name : string|null

No details available.

description : string|null

No details available.

required : bool|null

No details available.

deprecated : bool|null

No details available.

ref : OpenApi\Spec\Schema\Ref|string|null

No details available.

explode : bool|null

No details available.

schema : OpenApi\Spec\Schema|null

No details available.

example : mixed|null

No details available.

examples : list<OA\Example>|null

No details available.

content : OA\MediaType|list<OA\MediaType>|null

No details available.

Reference ​

Parameter\Header ​

A parameter passed via an HTTP header.

Allowed in ​

Operation, PathItem

Parameters ​

parameter : string|null

No details available.

name : string|null

No details available.

description : string|null

No details available.

required : bool|null

No details available.

deprecated : bool|null

No details available.

ref : OpenApi\Spec\Schema\Ref|string|null

No details available.

explode : bool|null

No details available.

schema : OpenApi\Spec\Schema|null

No details available.

example : mixed|null

No details available.

examples : list<OA\Example>|null

No details available.

content : OA\MediaType|list<OA\MediaType>|null

No details available.

Reference ​

Parameter\Path ​

A parameter passed via the URL path (always required).

Allowed in ​

Operation, PathItem

Parameters ​

parameter : string|null

No details available.

name : string|null

No details available.

description : string|null

No details available.

required : bool|null

No details available.

deprecated : bool|null

No details available.

ref : OpenApi\Spec\Schema\Ref|string|null

No details available.

style : OpenApi\Spec\ParameterStyle|string|null

No details available.

explode : bool|null

No details available.

schema : OpenApi\Spec\Schema|null

No details available.

example : mixed|null

No details available.

examples : list<OA\Example>|null

No details available.

content : OA\MediaType|list<OA\MediaType>|null

No details available.

Reference ​

Parameter\Query ​

A parameter passed via the URL query string.

Allowed in ​

Operation, PathItem

Parameters ​

parameter : string|null

No details available.

name : string|null

No details available.

description : string|null

No details available.

required : bool|null

No details available.

deprecated : bool|null

No details available.

allowEmptyValue : bool|null

No details available.

ref : OpenApi\Spec\Schema\Ref|string|null

No details available.

style : OpenApi\Spec\ParameterStyle|string|null

No details available.

explode : bool|null

No details available.

allowReserved : bool|null

No details available.

schema : OpenApi\Spec\Schema|null

No details available.

example : mixed|null

No details available.

examples : list<OA\Example>|null

No details available.

content : OA\MediaType|list<OA\MediaType>|null

No details available.

Reference ​

PathItem ​

Describes shared metadata for all operations under a path.

Place on a controller class — the path is inferred from its operations. Parameters, summary, description and servers are emitted at path level in the OpenAPI output. Prefix, tags, security and responses are controller-level features that compose via class hierarchy and apply to all contained operations.

Shared path-level properties (parameters, summary, description, servers per OpenAPI spec):

#[PathItem(parameters: [new Parameter\Path(name: 'id', schema: new Schema(type: 'integer'))])] class ProductController { #[Operation\Get(path: '/products/{id}')] public function get() {} }

The path in the output is inferred from the operations — no need to declare it on PathItem, avoiding duplication.

Prefix composition with inherited metadata:

#[PathItem(prefix: '/api/v1')] class BaseController {}

#[PathItem(prefix: '/users', tags: ['Users'], security: [new Security\Requirement(scheme: 'bearerAuth')])] #[Response(response: 401, description: 'Unauthorized')] #[Response(response: 500, description: 'Server error')] class UserController extends BaseController { #[Operation\Get(path: '/list')] // resolved: /api/v1/users/list, tags: ['Users'] public function list() {}

  #[Operation\Get(path: '/{id}')]       // resolved: /api/v1/users/{id}, tags: ['Users']
  public function get() {}

}

Prefixes compose by walking the class hierarchy — each ancestor PathItem contributes its prefix segment. All collection properties merge additively: tags, security, responses, and parameters accumulate from the full ancestor chain. Deduplication is by value (tags), by scheme (security), by status code (responses), and by name+in (parameters).

Nested elements ​

Parameter, Parameter\Cookie, Parameter\Header, Parameter\Path, Parameter\Query, Response, Security\Requirement, Server

Parameters ​

ref : string|null

A JSON Reference to a reusable path item

prefix : string|null

Path prefix — composable via class hierarchy

summary : string|null

An optional summary, intended to apply to all operations in this path

description : string|null

An optional description, intended to apply to all operations in this path

parameters : list<Parameter>|null

Parameters applicable to all operations under this path

servers : list<Server>|null

Alternative servers for all operations under this path

tags : list<string>|null

Tags to clone to contained operations

security : list<Security\Requirement>|null

Security requirements to clone to contained operations

responses : list<Response>|null

Shared responses to clone to contained operations

Reference ​

Property ​

Defines a single property within a Schema object.

The name comes from the property, parameter or constant the attribute sits on. A method supplies none, so a getter needs property: explicitly; without it the property is reported as missing one and omitted.

Allowed in ​

Schema

Parameters ​

property : string|null

The property name

schema : Schema|null

The schema defining the property type and constraints

Reference ​

Property\Encoded ​

Shortcut for a property that carries its own encoding definition.

Instead of declaring OA\Encoding separately on the OA\MediaType, this attribute bundles property and encoding together. The MediaTypes augmenter promotes the nested encoding to the parent MediaType automatically.

Allowed in ​

Schema

Parameters ​

property : string|null

The property name

schema : OA\Schema|null

The schema defining the property type and constraints

encoding : OpenApi\Spec\Encoding|null

No details available.

Reference ​

RequestBody ​

Describes a single request body.

Allowed in ​

Operation

Nested elements ​

MediaType, MediaType\Json, MediaType\Xml

Parameters ​

request : string|null

Reusable request body identifier (component key)

description : string|null

A brief description of the request body (CommonMark syntax)

required : bool|null

Whether the request body is required

ref : string|Schema\Ref|null

A JSON Reference to a reusable request body

content : MediaType|list<MediaType>|null

The content of the request body

Reference ​

Response ​

Describes a single response from an API operation.

Allowed in ​

Operation, PathItem

Nested elements ​

Header, Link, MediaType, MediaType\Json, MediaType\Xml

Parameters ​

response : string|int|null

The HTTP status code or 'default'

description : string|null

A description of the response (CommonMark syntax)

ref : string|Schema\Ref|null

A JSON Reference to a reusable response

headers : list<Header>|null

Headers sent with the response

content : MediaType|list<MediaType>|null

Possible response payloads

links : list<Link>|null

Design-time links for the response

Reference ​

Schema ​

Defines the structure and validation rules for a data type.

On a class — becomes a reusable component schema (name inferred from class):

#[OA\Schema] class Pet { #[OA\Property] public string $name; #[OA\Property] public ?int $age; }

Produces: components: schemas: Pet: type: object properties: name: { type: string } age:

Inline — used within parameters, responses, or other schemas:

new OA\Schema(type: 'array', items: new OA\Schema(ref: Pet::class))

Only a class supplies a name. On a method or a parameter, pass schema: explicitly; without it the schema has no component key and is reported as missing one.

Allowed in ​

Components, Property, Parameter, Header, MediaType

Nested elements ​

Property, Property\Encoded

Parameters ​

schema : string|null

Reusable schema identifier (component key)

title : string|null

A title for the schema

description : string|null

A description of the schema (CommonMark syntax)

ref : string|null

A JSON Reference to a reusable schema

type : string|list<string>|null

The value type(s) (string, number, integer, boolean, array, object, null)

format : string|null

Further refines the type (e.g. int32, int64, float, double, date-time, email)

nullable : bool|null

Whether the value can be null (OAS 3.0 only; use type array in 3.1+)

minLength : int|null

Minimum string length

maxLength : int|null

Maximum string length

pattern : string|null

Regular expression pattern the string must match

contentMediaType : string|null

The media type of string content encoding

contentEncoding : string|null

The encoding used for string content (e.g. base64)

minimum : int|float|null

Minimum numeric value (inclusive)

maximum : int|float|null

Maximum numeric value (inclusive)

exclusiveMinimum : int|float|bool|null

Exclusive minimum value

exclusiveMaximum : int|float|bool|null

Exclusive maximum value

multipleOf : int|float|null

The value must be a multiple of this number

items : Schema|string|null

Schema for array items

minItems : int|null

Minimum number of array items

maxItems : int|null

Maximum number of array items

uniqueItems : bool|null

Whether array items must be unique

prefixItems : list<Schema>|null

Schemas for positional array items (tuple validation)

contains : Schema|bool|null

Schema that at least one array item must match

minContains : int|null

Minimum number of items matching contains

maxContains : int|null

Maximum number of items matching contains

unevaluatedItems : Schema|bool|null

Schema for items not covered by other keywords

properties : list<Property>|null

Object property definitions

required : list<string>|null

List of required property names

additionalProperties : Schema|Schema\AdditionalProperties|bool|null

Schema or boolean for additional properties

patternProperties : array<string,Schema>|null

Schemas for properties matching regex patterns

minProperties : int|null

Minimum number of properties

maxProperties : int|null

Maximum number of properties

unevaluatedProperties : Schema|bool|null

Schema for properties not covered by other keywords

propertyNames : Schema|null

Schema that property names must validate against

dependentRequired : array<string,list<string>>|null

Property-level required dependencies

dependentSchemas : array<string,Schema>|null

Property-level schema dependencies

allOf : list<Schema>|null

All schemas must match (AND composition)

anyOf : list<Schema>|null

At least one schema must match (OR composition)

oneOf : list<Schema>|null

Exactly one schema must match (XOR composition)

not : Schema|null

The schema must NOT match

if : Schema|null

Conditional schema (if-then-else)

then : Schema|null

Applied when 'if' succeeds

else : Schema|null

Applied when 'if' fails

enum : list<string|int|float|bool|\UnitEnum|class-string<\UnitEnum>|null>|null

Allowed values

const : mixed

A single allowed value

example : mixed

An example value

examples : list<mixed>|null

A list of example values

deprecated : bool|null

Whether the schema is deprecated

readOnly : bool|null

Whether the value is read-only

writeOnly : bool|null

Whether the value is write-only

default : mixed

The default value

discriminator : Discriminator|null

Discriminator for polymorphism

externalDocs : ExternalDocumentation|null

Additional external documentation

xml : Xml|null

XML representation metadata

Reference ​

Schema\AdditionalProperties ​

Typed alias for Schema used as the additionalProperties value.

Identical to OA\Schema in functionality — exists for readability when declaring schemas with constrained additional properties:

new OA\Schema(
    type: 'object',
    additionalProperties: new OA\Schema\AdditionalProperties(type: 'string'),
)

Allowed in ​

Components, Property, Parameter, Header, MediaType

Parameters ​

schema : string|null

Reusable schema identifier (component key)

title : string|null

A title for the schema

description : string|null

A description of the schema (CommonMark syntax)

ref : string|null

A JSON Reference to a reusable schema

type : string|list<string>|null

The value type(s) (string, number, integer, boolean, array, object, null)

format : string|null

Further refines the type (e.g. int32, int64, float, double, date-time, email)

nullable : bool|null

Whether the value can be null (OAS 3.0 only; use type array in 3.1+)

minLength : int|null

Minimum string length

maxLength : int|null

Maximum string length

pattern : string|null

Regular expression pattern the string must match

contentMediaType : string|null

The media type of string content encoding

contentEncoding : string|null

The encoding used for string content (e.g. base64)

minimum : int|float|null

Minimum numeric value (inclusive)

maximum : int|float|null

Maximum numeric value (inclusive)

exclusiveMinimum : int|float|bool|null

Exclusive minimum value

exclusiveMaximum : int|float|bool|null

Exclusive maximum value

multipleOf : int|float|null

The value must be a multiple of this number

items : Schema|string|null

Schema for array items

minItems : int|null

Minimum number of array items

maxItems : int|null

Maximum number of array items

uniqueItems : bool|null

Whether array items must be unique

prefixItems : list<Schema>|null

Schemas for positional array items (tuple validation)

contains : Schema|bool|null

Schema that at least one array item must match

minContains : int|null

Minimum number of items matching contains

maxContains : int|null

Maximum number of items matching contains

unevaluatedItems : Schema|bool|null

Schema for items not covered by other keywords

properties : list<Property>|null

Object property definitions

required : list<string>|null

List of required property names

additionalProperties : Schema|Schema\AdditionalProperties|bool|null

Schema or boolean for additional properties

patternProperties : array<string,Schema>|null

Schemas for properties matching regex patterns

minProperties : int|null

Minimum number of properties

maxProperties : int|null

Maximum number of properties

unevaluatedProperties : Schema|bool|null

Schema for properties not covered by other keywords

propertyNames : Schema|null

Schema that property names must validate against

dependentRequired : array<string,list<string>>|null

Property-level required dependencies

dependentSchemas : array<string,Schema>|null

Property-level schema dependencies

allOf : list<Schema>|null

All schemas must match (AND composition)

anyOf : list<Schema>|null

At least one schema must match (OR composition)

oneOf : list<Schema>|null

Exactly one schema must match (XOR composition)

not : Schema|null

The schema must NOT match

if : Schema|null

Conditional schema (if-then-else)

then : Schema|null

Applied when 'if' succeeds

else : Schema|null

Applied when 'if' fails

enum : list<string|int|float|bool|\UnitEnum|class-string<\UnitEnum>|null>|null

Allowed values

const : mixed

A single allowed value

example : mixed

An example value

examples : list<mixed>|null

A list of example values

deprecated : bool|null

Whether the schema is deprecated

readOnly : bool|null

Whether the value is read-only

writeOnly : bool|null

Whether the value is write-only

default : mixed

The default value

discriminator : Discriminator|null

Discriminator for polymorphism

externalDocs : ExternalDocumentation|null

Additional external documentation

xml : Xml|null

XML representation metadata

Schema\Items ​

Shortcut for OA\Schema with type array and items.

Allows to shorten this:

#[OA\Schema] class Pet { #[OA\Property] #[OA\Schema(type: 'array', items: new OA\Schema(ref: MyModel::class))] public array $names; }

to this:

#[OA\Schema] class Pet { #[OA\Schema\Items(ref: MyModel::class)] public array $names; }

Since Items extends Schema, the implicit OA\Property shortcut applies — no explicit #[OA\Property] is needed. The Shortcuts augmenter wraps this into OA\Schema(type: 'array', items: ...) automatically.

Allowed in ​

Components, Property, Parameter, Header, MediaType

Parameters ​

schema : string|null

Reusable schema identifier (component key)

title : string|null

A title for the schema

description : string|null

A description of the schema (CommonMark syntax)

ref : string|null

A JSON Reference to a reusable schema

type : string|list<string>|null

The value type(s) (string, number, integer, boolean, array, object, null)

format : string|null

Further refines the type (e.g. int32, int64, float, double, date-time, email)

nullable : bool|null

Whether the value can be null (OAS 3.0 only; use type array in 3.1+)

minLength : int|null

Minimum string length

maxLength : int|null

Maximum string length

pattern : string|null

Regular expression pattern the string must match

contentMediaType : string|null

The media type of string content encoding

contentEncoding : string|null

The encoding used for string content (e.g. base64)

minimum : int|float|null

Minimum numeric value (inclusive)

maximum : int|float|null

Maximum numeric value (inclusive)

exclusiveMinimum : int|float|bool|null

Exclusive minimum value

exclusiveMaximum : int|float|bool|null

Exclusive maximum value

multipleOf : int|float|null

The value must be a multiple of this number

items : Schema|string|null

Schema for array items

minItems : int|null

Minimum number of array items

maxItems : int|null

Maximum number of array items

uniqueItems : bool|null

Whether array items must be unique

prefixItems : list<Schema>|null

Schemas for positional array items (tuple validation)

contains : Schema|bool|null

Schema that at least one array item must match

minContains : int|null

Minimum number of items matching contains

maxContains : int|null

Maximum number of items matching contains

unevaluatedItems : Schema|bool|null

Schema for items not covered by other keywords

properties : list<Property>|null

Object property definitions

required : list<string>|null

List of required property names

additionalProperties : Schema|Schema\AdditionalProperties|bool|null

Schema or boolean for additional properties

patternProperties : array<string,Schema>|null

Schemas for properties matching regex patterns

minProperties : int|null

Minimum number of properties

maxProperties : int|null

Maximum number of properties

unevaluatedProperties : Schema|bool|null

Schema for properties not covered by other keywords

propertyNames : Schema|null

Schema that property names must validate against

dependentRequired : array<string,list<string>>|null

Property-level required dependencies

dependentSchemas : array<string,Schema>|null

Property-level schema dependencies

allOf : list<Schema>|null

All schemas must match (AND composition)

anyOf : list<Schema>|null

At least one schema must match (OR composition)

oneOf : list<Schema>|null

Exactly one schema must match (XOR composition)

not : Schema|null

The schema must NOT match

if : Schema|null

Conditional schema (if-then-else)

then : Schema|null

Applied when 'if' succeeds

else : Schema|null

Applied when 'if' fails

enum : list<string|int|float|bool|\UnitEnum|class-string<\UnitEnum>|null>|null

Allowed values

const : mixed

A single allowed value

example : mixed

An example value

examples : list<mixed>|null

A list of example values

deprecated : bool|null

Whether the schema is deprecated

readOnly : bool|null

Whether the value is read-only

writeOnly : bool|null

Whether the value is write-only

default : mixed

The default value

discriminator : Discriminator|null

Discriminator for polymorphism

externalDocs : ExternalDocumentation|null

Additional external documentation

xml : Xml|null

XML representation metadata

Reference ​

Schema\Ref ​

A reference-only schema — $ref is required, most other Schema properties are unavailable.

In OpenAPI 3.1+, $ref can be combined with title and description to override the referenced schema's metadata without duplicating the definition.

Usage: #[OA\Property(schema: new OA\Schema\Ref(ref: Pet::class))] #[OA\Property(schema: new OA\Schema\Ref(ref: '#/components/schemas/Pet', title: 'The pet'))] #[OA\Property(schema: new OA\Schema\Ref(ref: Pet::class, description: 'Override desc'))]

If used on a $ref directly, only the ref value is used.

Allowed in ​

Components, Property, Parameter, Header, MediaType

Parameters ​

ref : string

No details available.

title : string|null

No details available.

description : string|null

No details available.

Security\Requirement ​

A security requirement declaring which security schemes apply.

Each requirement instance represents one entry in the security array (OR logic). Multiple schemes within a single requirement represent AND logic.

Allowed in ​

OpenApi, Operation, PathItem

Parameters ​

scheme : string|null

Single scheme name (shorthand for simple requirements)

scopes : list<string>|null

Scopes for the single scheme (OAuth2/OpenIdConnect)

schemes : array<string,list<string>>|null

Map of scheme names to scopes (for AND logic with multiple schemes)

Reference ​

Security\Scheme ​

Defines a security scheme that can be used by the operations.

Typed subtypes are available for each security scheme type:

  • OA\Security\Scheme\Http - HTTP authentication (Basic, Bearer, etc.)
  • OA\Security\Scheme\ApiKey - API key in header, query, or cookie
  • OA\Security\Scheme\OAuth2 - OAuth2 with one or more flows
  • OA\Security\Scheme\OpenIdConnect - OpenID Connect discovery
  • OA\Security\Scheme\MutualTls - Mutual TLS authentication

Allowed in ​

Components

Nested elements ​

Flow, Flow\AuthorizationCode, Flow\ClientCredentials, Flow\Implicit, Flow\Password

Parameters ​

securityScheme : string|null

Reusable security scheme identifier (component key)

type : string|OA\SchemeType|null

The type of the security scheme (apiKey, http, mutualTLS, oauth2, openIdConnect)

description : string|null

A description of the security scheme (CommonMark syntax)

name : string|null

The name of the header, query, or cookie parameter (apiKey)

in : string|OA\SchemeIn|null

The location of the API key (query, header, cookie)

scheme : string|null

The HTTP authorization scheme (http)

bearerFormat : string|null

A hint about the format of the bearer token (http/bearer)

openIdConnectUrl : string|null

The OpenID Connect URL to discover configuration (openIdConnect)

flows : list<OA\Flow>|null

The available OAuth2 flows (oauth2)

ref : string|null

A JSON Reference to a reusable security scheme

Reference ​

Security\Scheme\ApiKey ​

An API key security scheme (header, query, or cookie).

Allowed in ​

Components

Parameters ​

securityScheme : string|null

No details available.

description : string|null

No details available.

name : string|null

No details available.

in : OpenApi\Spec\SchemeIn|string|null

No details available.

Reference ​

Security\Scheme\Http ​

An HTTP authentication security scheme (Basic, Bearer, etc.).

Allowed in ​

Components

Parameters ​

securityScheme : string|null

No details available.

description : string|null

No details available.

scheme : string|null

No details available.

bearerFormat : string|null

No details available.

Reference ​

Security\Scheme\MutualTls ​

A Mutual TLS security scheme.

Allowed in ​

Components

Parameters ​

securityScheme : string|null

No details available.

description : string|null

No details available.

Reference ​

Security\Scheme\OAuth2 ​

An OAuth2 security scheme with one or more flows.

Allowed in ​

Components

Parameters ​

securityScheme : string|null

No details available.

description : string|null

No details available.

flows : list<OA\Flow>|null

No details available.

Reference ​

Security\Scheme\OpenIdConnect ​

An OpenID Connect Discovery security scheme.

Allowed in ​

Components

Parameters ​

securityScheme : string|null

No details available.

description : string|null

No details available.

openIdConnectUrl : string|null

No details available.

Reference ​

Server ​

A host the API is available on, optionally templated with ServerVariable substitutions.

Allowed in ​

Operation, PathItem

Nested elements ​

ServerVariable

Parameters ​

url : string|null

A URL to the target host

description : string|null

A description of the host (CommonMark syntax)

variables : list<ServerVariable>|null

Variables for server URL template substitution

Reference ​

ServerVariable ​

The allowed and default substitutions for one template variable in a Server URL.

Allowed in ​

Server

Parameters ​

serverVariable : string|null

The variable name

default : string|null

The default value to use for substitution

description : string|null

A description of the server variable (CommonMark syntax)

enum : list<string>|null

Enumeration of allowed string values for substitution

Reference ​

Tag ​

Adds metadata to a single tag used by the Operation Object.

Nested elements ​

ExternalDocumentation

Parameters ​

name : string|null

The name of the tag

summary : string|null

A short summary of the tag, used for display purposes

description : string|null

A description of the tag (CommonMark syntax)

externalDocs : ExternalDocumentation|null

Additional external documentation for this tag

parent : string|null

The name of a tag that this tag is nested under

kind : string|null

A machine-readable string to categorize the tag

Reference ​

Xml ​

Metadata for XML representation of a schema property.

Allowed in ​

Schema

Parameters ​

name : string|null

Replaces the name of the element/attribute

namespace : string|null

The URI of the XML namespace

prefix : string|null

The namespace prefix to use

attribute : bool|null

Whether the property translates to an XML attribute

wrapped : bool|null

Whether array items are wrapped in an additional element

Reference ​