How to define and use a reuseable parameter list for swagger in php
Stefan Bogdanescu
Founder & Senior Architect · 2026-06-29
# Mastering Reusability: Defining Reusable Parameter Lists for Swagger in PHP
As developers building robust APIs, the documentationâespecially API specification generated by tools like Swagger/OpenAPIâneeds to be accurate, consistent, and maintainable. When using packages like `swagger-php` to generate OpenAPI specifications from PHP annotations, a common hurdle arises: how do we avoid tediously repeating common parameters (like headers, pagination settings, or global filters) across every single route definition?
This post dives deep into how you can define and utilize reusable parameter lists in your Swagger documentation, moving beyond individual `@OA\Parameter` definitions to create clean, maintainable specifications.
## The Challenge of Repetition in API Documentation
When documenting an endpoint, we often deal with two types of parameters: path parameters (like `{season_id}`), which are unique to the route, and global parameters (query strings or headers) that apply across many endpoints.
As you discovered while using `swagger-php`, defining these globally requires referencing components within your OpenAPI schema. The difficulty lies in structuring the `@OA\Get` annotation to seamlessly integrate both route-specific requirements and reusable global settings. Simply placing a generic reference often fails because the structure of the parameters array must conform strictly to the OpenAPI specification rules.
## The Solution: Leveraging OpenAPI Components for Reusability
The core principle behind reusability in OpenAPI is defining definitions within the `components` section of your specification. These components can then be referenced using the `$ref` mechanism. For parameters, this means defining a reusable set of parameters and referencing that set where needed.
Instead of trying to wrap a list directly into an `@OA\Link` (which is typically used for linking between documents or external URLs), we need to structure the route annotation to hold a collection of parameters, allowing us to inject our reusable definitions.
### Step 1: Define Reusable Parameter Schemas in Components
First, you must define your common parameter groups in your global components file (often within a separate annotation file or directly within the main specification context). This allows these definitions to be referenced by name.
For example, let's assume we want a reusable set of query parameters for filtering and sorting:
```php
/**
* @OA\Parameter(
* // Define the reusable list for pagination/sorting
* ref="#/components/parameters/PaginationParams"
* )
*/
class ReusableParameters {}
```
And in your components definition, you define the actual structure:
```yaml
components:
parameters:
PaginationParams:
type: object
properties:
page:
type: integer
description: "The page number to retrieve."
pageSize:
type: integer
description: "The number of items per page."
sortBy:
type: string
description: "Field to sort the results by."
```
### Step 2: Integrating Reusable Lists into Route Annotations
Now, within your route definition, you can use the `parameters` array within `@OA\Get` and reference these components. When dealing with mixed parameters (path vs. query), you define them explicitly in the list, referencing the reusable definitions where applicable.
Here is how you combine a required path parameter (`id`) with a set of reusable global query parameters:
```php
/**
* @OA\Get(
* path="/api/v2/seasons/{season_id}",
* description="Show season(s).",
* summary="List season(s) from comma separated id list",
* tags={"seasons"},
* security = { { "basicAuth": {} } },
* parameters={
* // 1. Route-specific parameter (must be defined here)
* @OA\Parameter(
* name="id", in="path", required=true, @OA\Schema(type="integer")
* ),
* // 2. Reusable global parameters list
* @OA\Parameter(ref="#/components/parameters/PaginationParams"),
* @OA\Parameter(ref="#/components/parameters/CatalogHeader"),
* @OA\Parameter(ref="#/components/parameters/SiteHeader"),
* },
* @OA\Response(response=200, ref="#/components/responses/200",
* @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/SeasonResponse"))
* ),
* @OA\Response(response=404, ref="#/components/responses/404"),
* )
*/
```
By structuring the route annotation to contain an array of `@OA\Parameter` definitionsâsome specific and some referencedâyou achieve the desired level of reuse while maintaining the necessary specificity for path variables. This approach aligns perfectly with designing highly structured APIs, much like adhering to best practices seen in frameworks like Laravel where component-based design is emphasized.
## Conclusion
Creating reusable documentation structures in Swagger requires thinking about your OpenAPI specification as a collection of components rather than a flat list of annotations. By strictly utilizing `$ref` within the `parameters` array of your route definitions, you can effectively decouple your route logic from repetitive parameter definitions. This makes your API documentation cleaner, easier to maintain, and significantly more scalable as your project grows. Embrace component-based design; it is the professional way to handle complex data structuring in modern PHP development.