Merge branch '4.0'

extra/releases.md

@@ -15,8 +15,8 @@ For example:
 
 3 versions are maintained at the same time:
 
-* **stable** (currently the **3.2** branch): regular bugfixes are integrated in this version
-* **old-stable** (are the last 2 minor branches: currently **3.0** and **3.1** branches): [security fixes](security.md) are integrated in this version, regular bugfixes are **not** backported in it
+* **stable** (currently the **4.0** branch): regular bugfixes are integrated in this version
+* **old-stable** (are the last 2 minor branches: currently **3.4** and **3.3** branches): [security fixes](security.md) are integrated in this version, regular bugfixes are **not** backported in it
 * **development** (**main** branch): new features target this branch
 
 Older versions (1.x, 2.6...) **are not maintained**. If you still use them, you must upgrade as soon as possible.

laravel/index.md

@@ -22,7 +22,7 @@ With API Platform, you can:
 <!-- * benefits from native HTTP cache (with automatic invalidation) -->
 * boost your app with [Octane](https://laravel.com/docs/octane) and [FrankenPHP](https://frankenphp.dev) (the default Octane engine, also created by Kévin)
 * [decouple your API from your models](../core/state-providers.md) and implement patterns such as CQRS
-* test your API using convenient ad-hoc assertions that works with Pest and PHPUnit
+* test your API using convenient ad-hoc assertions that work with Pest and PHPUnit
 
 Let's discover how to use API Platform with Laravel!
 
@@ -44,10 +44,20 @@ cd my-api-platform-laravel-app
 In your Laravel project, install the API Platform integration for Laravel:
 
 ```console
-composer require api-platform/laravel:^4
+composer require api-platform/laravel
 ```
 
-If it's not already done, run `php artisan serve` to start the built-in web server.
+After installing API Platform, publish its assets and config:
+
+```console
+php artisan api-platform:install
+```
+
+If it's not already done, start the built-in web server:
+
+```console
+php artisan serve
+```
 
 Open `http://127.0.0.1:8000/api/`, your API is already active and documented... but empty!
 
@@ -126,7 +136,7 @@ namespace App\Models;
  }
 ```
 
-Open `http://127.0.0.1:8000/api/`, tadam, your API is ready and **entirely functionnal** 🎉:
+Open `http://127.0.0.1:8000/api/`, tadam, your API is ready and **entirely functional** 🎉:
 
 ![Basic REST API](images/basic-rest.png)
 
@@ -271,7 +281,7 @@ class Book extends Model
 
 ## Relations and Nested Resources
 
-Let's replace our author column by a relation to a new `author` table:
+Let's replace our author column with a relation to a new `author` table:
 
 ```patch
     public function up(): void
@@ -295,7 +305,7 @@ Let's replace our author column by a relation to a new `author` table:
     }
 ```
 
-By doing so, API Platform will automatically handle links to that relation using your prefered format (JSON:API, JSON-LD etc)
+By doing so, API Platform will automatically handle links to that relation using your preferred format (JSON:API, JSON-LD, etc)
 and when we request a Book we obtain:
 
 ```json
@@ -559,7 +569,49 @@ It also natively supports:
 * [Laravel Passport](https://laravel.com/docs/passport), a full OAuth 2 server
 * [Laravel Socialite](https://laravel.com/docs/socialite), OAuth providers including Facebook, X, LinkedIn, Google, GitHub, GitLab, Bitbucket, and Slack
 
-Follow the official instructions of the tool(s) you want to use.
+Follow the official instructions for the tool(s) you want to use.
+
+### Login With Swagger UI
+
+In Swagger UI, you can authenticate your requests using the `Authorize` button in the top right corner.
+To use it, you need to add some configuration in the `config/api-platform.php` file.
+
+Here is an example of how to configure API key authentication:
+
+```php
+// config/api-platform.php
+'swagger_ui' => [
+    'enabled' => true,
+    'apiKeys' => [
+        'api' => [
+            'type' => 'header',
+            'name' => 'X-API-Key'
+        ]
+    ]
+]
+```
+
+Or if you are using Laravel Passport (or any other OAuth server):
+
+```php
+// config/api-platform.php
+'swagger_ui' => [
+    'enabled' => true,
+    'oauth' => [
+        'enabled' => true,
+        'type' => 'oauth2',
+        'flow' => 'authorizationCode',
+        'tokenUrl' => '<oauth_token_endpoint>',
+        'authorizationUrl' =>'<oauth_authorization_endpoint>',
+        'refreshUrl' => '<oauth_refresh_endpoint>',
+        'scopes' => ['scope' => 'Description of the scope'],
+        'pkce' => true,
+    ]
+]
+```
+
+A combination of both is also possible.
+For more information, you can also check the [Swagger UI documentation](https://swagger.io/docs/specification/authentication/).
 
 ### Middlewares