mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-03 08:09:25 +03:00
78664ef9ec
* Initial pass for OA3 upgrade * Fix Util Tests * Fix first batch of Unit Tests. Up to Model * Another batch of fixed tests * Update annotations * Convert Model & Property Describers * Update tests, Fix RouteDescribers, FIx additional bugs * Another batch of updates * Another batch of fixed Functional Tests * Fix FunctionalTest tests * Fix Bazinga Tests * FIx FOS Rest * Fix JMS TEsts & describers * Fix all Tests * Fix few stuff from own CR * CS Fixes * CS Fixes 2 * CS Fixes 3 * CS Fixes 4 * Remove collection bug * Updates after first CRs * CS * Drop support for SF3 * Update the docs * Add an upgrade guide * misc doc fixes * Configurable media types * Code Style Fixes * Don't use ::$ref for @Response and @RequestBody * Fix upgrading guide * Fix OA case Co-authored-by: Filip Benčo <filip.benco@websupport.sk> Co-authored-by: Guilhem Niot <guilhem.niot@gmail.com> Co-authored-by: Mantis Development <mantis@users.noreply.github.com>
29 lines
1.9 KiB
Markdown
29 lines
1.9 KiB
Markdown
Upgrading From 3.x To 4.0
|
|
=========================
|
|
|
|
Version 4 is a major change introducing OpenAPI 3.0 support, the rebranded swagger specification, which brings a set of new interesting features. Unfortunately this required a rework to a large part of the bundle, and introduces BC breaks.
|
|
|
|
The Visual guide to "[What's new in 3.0 spec](https://blog.readme.com/an-example-filled-guide-to-swagger-3-2/)" gives more information on OpenApi 3.0.
|
|
|
|
Version 4 does not support older versions of the specification. If you need to output swagger v2 documentation, you will need to use the latest 3.x release.
|
|
|
|
The Upgrade to Swagger 3.0
|
|
--------------------------
|
|
|
|
The biggest part of the upgrade will most likely be the upgrade of the library `zircote/swagger-php` to `3.0` which introduces new annotations in order to support OpenAPI 3.0 but also changes
|
|
their namespace from ``Swagger`` to ``OpenApi``.
|
|
|
|
They created a dedicated page to help you upgrade : https://zircote.github.io/swagger-php/Migrating-to-v3.html.
|
|
|
|
Here are some additional advices that are more likely to apply to NelmioApiDocBundle users:
|
|
|
|
- Upgrade all your ``use Swagger\Annotations as SWG`` statements to ``use OpenApi\Annotations as OA;`` (to simplify the upgrade you may also stick to the ``SWG`` aliasing).
|
|
In case you changed ``SWG`` to ``OA``, upgrade all your annotations from ``@SWG\...`` to ``@OA\...``.
|
|
|
|
- Update your config in case you used inlined swagger docummentation (the field ``nelmio_api_doc.documentation``). [A tool](https://openapi-converter.herokuapp.com/) is available to help you convert it.
|
|
|
|
- In case you used ``@OA\Response(..., @OA\Schema(...))``, you should explicit your media type by using the annotation ``@OA\JsonContent`` or ``@OA\XmlContent`` instead of ``@OA\Schema``:
|
|
``@OA\Response(..., @OA\JsonContent(...))`` or ``@OA\Response(..., @OA\XmlContent(...))``.
|
|
|
|
When you use ``@Model`` directly (``@OA\Response(..., @Model(...)))``), the media type is set by default to ``json``.
|