# Spec Attribute Reference This page is generated automatically from the `swagger-php` sources. For improvements head over to [GitHub](https://github.com/zircote/swagger-php) 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](/reference/architecture) resolves nesting, and [Augmenters](/reference/augmenters.md) 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](https://github.com/zircote/swagger-php/tree/master/src/Spec/Attachable.php) 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](https://github.com/zircote/swagger-php/tree/master/src/Spec/Components.php) 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](https://github.com/zircote/swagger-php/tree/master/src/Spec/Contact.php) 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 --- - [Contact Object](https://spec.openapis.org/oas/v3.1.1.html#contact-object) ↗ ### [Discriminator](https://github.com/zircote/swagger-php/tree/master/src/Spec/Discriminator.php) 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 --- - [Discriminator Object](https://spec.openapis.org/oas/v3.1.1.html#discriminator-object) ↗ ### [Encoding](https://github.com/zircote/swagger-php/tree/master/src/Spec/Encoding.php) 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 --- - [Encoding Object](https://spec.openapis.org/oas/v3.1.1.html#encoding-object) ↗ ### [Example](https://github.com/zircote/swagger-php/tree/master/src/Spec/Example.php) 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 --- - [Example Object](https://spec.openapis.org/oas/v3.1.1.html#example-object) ↗ ### [ExternalDocumentation](https://github.com/zircote/swagger-php/tree/master/src/Spec/ExternalDocumentation.php) 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 --- - [External Documentation Object](https://spec.openapis.org/oas/v3.1.1.html#external-documentation-object) ↗ ### [Flow](https://github.com/zircote/swagger-php/tree/master/src/Spec/Flow.php) 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 --- - [OAuth Flow Object](https://spec.openapis.org/oas/v3.1.1.html#oauth-flow-object) ↗ - [OAuth Flows Object](https://spec.openapis.org/oas/v3.1.1.html#oauth-flows-object) ↗ ### [Flow\AuthorizationCode](https://github.com/zircote/swagger-php/tree/master/src/Spec/Flow/AuthorizationCode.php) 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 --- - [OAuth Flow Object](https://spec.openapis.org/oas/v3.1.1.html#oauth-flow-object) ↗ ### [Flow\ClientCredentials](https://github.com/zircote/swagger-php/tree/master/src/Spec/Flow/ClientCredentials.php) 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 --- - [OAuth Flow Object](https://spec.openapis.org/oas/v3.1.1.html#oauth-flow-object) ↗ ### [Flow\Implicit](https://github.com/zircote/swagger-php/tree/master/src/Spec/Flow/Implicit.php) 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 --- - [OAuth Flow Object](https://spec.openapis.org/oas/v3.1.1.html#oauth-flow-object) ↗ ### [Flow\Password](https://github.com/zircote/swagger-php/tree/master/src/Spec/Flow/Password.php) 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 --- - [OAuth Flow Object](https://spec.openapis.org/oas/v3.1.1.html#oauth-flow-object) ↗ ### [Header](https://github.com/zircote/swagger-php/tree/master/src/Spec/Header.php) 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 --- - [Header Object](https://spec.openapis.org/oas/v3.1.1.html#header-object) ↗ ### [Info](https://github.com/zircote/swagger-php/tree/master/src/Spec/Info.php) 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 --- - [Info Object](https://spec.openapis.org/oas/v3.1.1.html#info-object) ↗ ### [License](https://github.com/zircote/swagger-php/tree/master/src/Spec/License.php) 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 --- - [License Object](https://spec.openapis.org/oas/v3.1.1.html#license-object) ↗ ### [Link](https://github.com/zircote/swagger-php/tree/master/src/Spec/Link.php) 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 --- - [Link Object](https://spec.openapis.org/oas/v3.1.1.html#link-object) ↗ ### [MediaType](https://github.com/zircote/swagger-php/tree/master/src/Spec/MediaType.php) 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 --- - [Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object) ↗ ### [MediaType\Json](https://github.com/zircote/swagger-php/tree/master/src/Spec/MediaType/Json.php) 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 --- - [Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object) ↗ ### [MediaType\Xml](https://github.com/zircote/swagger-php/tree/master/src/Spec/MediaType/Xml.php) 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 --- - [Media Type Object](https://spec.openapis.org/oas/v3.1.1.html#media-type-object) ↗ ### [OpenApi](https://github.com/zircote/swagger-php/tree/master/src/Spec/OpenApi.php) 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 --- - [OpenAPI Object](https://spec.openapis.org/oas/v3.1.1.html#openapi-object) ↗ ### [Operation](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ - [Webhooks](https://spec.openapis.org/oas/v3.1.1.html#fixed-fields) ↗ ### [Operation\Delete](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Delete.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Get](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Get.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Head](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Head.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Options](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Options.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Patch](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Patch.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Post](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Post.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Put](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Put.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Operation\Trace](https://github.com/zircote/swagger-php/tree/master/src/Spec/Operation/Trace.php) 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 --- - [Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object) ↗ ### [Parameter](https://github.com/zircote/swagger-php/tree/master/src/Spec/Parameter.php) 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 --- - [Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object) ↗ ### [Parameter\Cookie](https://github.com/zircote/swagger-php/tree/master/src/Spec/Parameter/Cookie.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object) ↗ ### [Parameter\Header](https://github.com/zircote/swagger-php/tree/master/src/Spec/Parameter/Header.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object) ↗ ### [Parameter\Path](https://github.com/zircote/swagger-php/tree/master/src/Spec/Parameter/Path.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object) ↗ ### [Parameter\Query](https://github.com/zircote/swagger-php/tree/master/src/Spec/Parameter/Query.php) 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 --- - [Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object) ↗ ### [PathItem](https://github.com/zircote/swagger-php/tree/master/src/Spec/PathItem.php) 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 --- - [Path Item Object](https://spec.openapis.org/oas/v3.1.1.html#path-item-object) ↗ ### [Property](https://github.com/zircote/swagger-php/tree/master/src/Spec/Property.php) 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 --- - [Schema Object](https://spec.openapis.org/oas/v3.1.1.html#schema-object) ↗ ### [Property\Encoded](https://github.com/zircote/swagger-php/tree/master/src/Spec/Property/Encoded.php) 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 --- - [Encoding Object](https://spec.openapis.org/oas/v3.1.1.html#encoding-object) ↗ ### [RequestBody](https://github.com/zircote/swagger-php/tree/master/src/Spec/RequestBody.php) 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 --- - [Request Body Object](https://spec.openapis.org/oas/v3.1.1.html#request-body-object) ↗ ### [Response](https://github.com/zircote/swagger-php/tree/master/src/Spec/Response.php) 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 --- - [Response Object](https://spec.openapis.org/oas/v3.1.1.html#response-object) ↗ ### [Schema](https://github.com/zircote/swagger-php/tree/master/src/Spec/Schema.php) 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: { type: integer, nullable: true } 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)
contentSchema : Schema|null: Schema for the decoded content described by contentMediaType
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 Object](https://spec.openapis.org/oas/v3.1.1.html#schema-object) ↗ - [JSON Schema](https://json-schema.org/draft/2020-12/json-schema-validation) ↗ ### [Schema\AdditionalProperties](https://github.com/zircote/swagger-php/tree/master/src/Spec/Schema/AdditionalProperties.php) 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)
contentSchema : Schema|null: Schema for the decoded content described by contentMediaType
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](https://github.com/zircote/swagger-php/tree/master/src/Spec/Schema/Items.php) 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)
contentSchema : Schema|null: Schema for the decoded content described by contentMediaType
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 Object](https://spec.openapis.org/oas/v3.1.1.html#schema-object) ↗ ### [Schema\Ref](https://github.com/zircote/swagger-php/tree/master/src/Spec/Schema/Ref.php) 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](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Requirement.php) 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 Requirement Object](https://spec.openapis.org/oas/v3.1.1.html#security-requirement-object) ↗ ### [Security\Scheme](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Scheme.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object) ↗ ### [Security\Scheme\ApiKey](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Scheme/ApiKey.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object) ↗ ### [Security\Scheme\Http](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Scheme/Http.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object) ↗ ### [Security\Scheme\MutualTls](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Scheme/MutualTls.php) A Mutual TLS security scheme. #### Allowed in --- Components #### Parameters ---

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

#### Reference --- - [Security Scheme Object](https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object) ↗ ### [Security\Scheme\OAuth2](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Scheme/OAuth2.php) 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 Object](https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object) ↗ ### [Security\Scheme\OpenIdConnect](https://github.com/zircote/swagger-php/tree/master/src/Spec/Security/Scheme/OpenIdConnect.php) 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 --- - [Security Scheme Object](https://spec.openapis.org/oas/v3.1.1.html#security-scheme-object) ↗ ### [Server](https://github.com/zircote/swagger-php/tree/master/src/Spec/Server.php) 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 --- - [Server Object](https://spec.openapis.org/oas/v3.1.1.html#server-object) ↗ ### [ServerVariable](https://github.com/zircote/swagger-php/tree/master/src/Spec/ServerVariable.php) 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|int|float|bool|\UnitEnum|class-string<\UnitEnum>|null>|null: Allowed values for substitution; all cast to string in the specification

#### Reference --- - [Server Variable Object](https://spec.openapis.org/oas/v3.1.1.html#server-variable-object) ↗ ### [Tag](https://github.com/zircote/swagger-php/tree/master/src/Spec/Tag.php) 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 --- - [Tag Object](https://spec.openapis.org/oas/v3.1.1.html#tag-object) ↗ ### [Xml](https://github.com/zircote/swagger-php/tree/master/src/Spec/Xml.php) 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 --- - [XML Object](https://spec.openapis.org/oas/v3.1.1.html#xml-object) ↗