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 8.1+ attributes in the OpenApi\Spec namespace — the foundation of the spec-attributes pipeline (--mode spec or --mode hybrid).

They are immutable data containers with no serialization logic. Relationships between attributes are declared via contains() (what children an attribute absorbs) and merge() (what parent an attribute composes into). 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 ​

Schema, Parameter, Response, RequestBody, Header, Security\Scheme, Link, Example, PathItem

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, MediaType\Json, MediaType\Xml

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 ​

Components, Header, MediaType, MediaType\Json, MediaType\Xml, Parameter, Parameter\Cookie, Parameter\Header, Parameter\Path, Parameter\Query

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, Security\Scheme\ApiKey, Security\Scheme\Http, Security\Scheme\MutualTls, Security\Scheme\OAuth2, Security\Scheme\OpenIdConnect

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 ​

Components, Response

Nested elements ​

MediaType, Example

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|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 ​

Components, 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 ​

Header, Parameter, Parameter\Cookie, Parameter\Header, Parameter\Path, Parameter\Query, RequestBody, Response

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

Nested elements ​

Encoding, Example

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|Schema>|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

Nested elements ​

Encoding, Example

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|Schema>|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, Response, RequestBody, Server, Security\Requirement

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.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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\Head ​

Shorthand for an HTTP HEAD operation.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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\Options ​

Shorthand for an HTTP OPTIONS operation.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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\Patch ​

Shorthand for an HTTP PATCH operation.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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.

Nested elements ​

Parameter, Response, RequestBody, Server, Security\Requirement

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 ​

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 ​

Components, Operation, Operation\Delete, Operation\Get, Operation\Head, Operation\Options, Operation\Patch, Operation\Post, Operation\Put, Operation\Trace, PathItem

Nested elements ​

MediaType, Example

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|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

Nested elements ​

MediaType, Example

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 : 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

Nested elements ​

MediaType, Example

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 : 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

Nested elements ​

MediaType, Example

Parameters ​

  • parameter : string|null No details available.
  • name : string|null No details available.
  • description : string|null No details available.
  • deprecated : bool|null No details available.
  • 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

Nested elements ​

MediaType, Example

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 : 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).

Allowed in ​

Components

Nested elements ​

Parameter, Server, Response, Security\Requirement

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.

Allowed in ​

Schema, Schema\Items

Parameters ​

  • property : string|null The property name
  • schema : Schema|null The schema defining the property type and constraints

Reference ​

RequestBody ​

Describes a single request body.

Allowed in ​

Components, Operation, Operation\Delete, Operation\Get, Operation\Head, Operation\Options, Operation\Patch, Operation\Post, Operation\Put, Operation\Trace

Nested elements ​

MediaType

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|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 ​

Components, Operation, Operation\Delete, Operation\Get, Operation\Head, Operation\Options, Operation\Patch, Operation\Post, Operation\Put, Operation\Trace, PathItem

Nested elements ​

Header, MediaType, Link

Parameters ​

  • response : string|int|null The HTTP status code or 'default'
  • description : string|null A description of the response (CommonMark syntax)
  • ref : string|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))

Allowed in ​

Components, Schema, Schema\Items

Nested elements ​

Property, Schema

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|Schema>|null Object property definitions
  • required : list<string>|null List of required property names
  • additionalProperties : Schema|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\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\Property] #[OA\Schema\Items(ref: MyModel::class)] public array $names; }

The Shortcuts augmenter wraps this into OA\Schema(type: 'array', items: ...) automatically.

Allowed in ​

Property, Parameter, Header, MediaType

Nested elements ​

Property, Schema

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|Schema>|null Object property definitions
  • required : list<string>|null List of required property names
  • additionalProperties : Schema|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 ​

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, Operation\Delete, Operation\Get, Operation\Head, Operation\Options, Operation\Patch, Operation\Post, Operation\Put, Operation\Trace, 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

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).

Nested elements ​

Flow

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.).

Nested elements ​

Flow

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.

Nested elements ​

Flow

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.

Nested elements ​

Flow

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.

Nested elements ​

Flow

Parameters ​

  • securityScheme : string|null No details available.
  • description : string|null No details available.
  • openIdConnectUrl : string|null No details available.

Reference ​

Server ​

Represents a Server.

Allowed in ​

Operation, Operation\Delete, Operation\Get, Operation\Head, Operation\Options, Operation\Patch, Operation\Post, Operation\Put, Operation\Trace, 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 ​

Represents a Server Variable for server URL template substitution.

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
  • description : string|null A description of the tag (CommonMark syntax)
  • externalDocs : ExternalDocumentation|null Additional external documentation for this 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 ​