Migrating to v3
Swagger-PHP 3.x generates an openapi.json file that follows the OpenAPI Version 3.0.x Specification.
If you need to output the older 2.x specification, use OpenApi-php 2.x
The default output changed from JSON to YAML
This aligns better with the direction of the swagger documentation and examples. Annotations can't be used as string anymore, you'll need to call toYaml() or toJson() if you prefer the JSON format.
Updated CLI
- Added colors
- No output for successful execution (Removed summary)
- non-zero exit when an error occurred.
- Defaults to YAML
- Defaults to stdout. To save to openapi.yaml use
-oor>
Changed annotations
SWG is renamed to OA
The namespace is renamed from SWG (Swagger) to OA (OpenApi)
@SWG\Swagger() is renamed to @OA\OpenApi()
@SWG\Path() is renamed to @OA\PathItem()
The specification uses the term "Path Item Object", updated the annotation to reflect that.
@SWG\Definition() is removed
Use @OA\Schema() instead of @OA\Definition() and update the references from "#/definitions/something" to "#/components/schemas/something".
@SWG\Path is removed
Use @OA\PathItem instead of @SWG\Path and update references.
Consumes, produces field is removed from OpenAPI specification
Use @OA\MediaType to set data format.
Rename parameter references
Rename #/parameters/{parameter_name} to #/components/parameters/{parameter_name}
Rename response references
Rename #/responses/{response} to #/components/responses/{response}
Renamed cli
Renamed swagger to openapi