From 6c9856c9cee2d5900cd05020821919452606b53f Mon Sep 17 00:00:00 2001 From: Tobias Oitzinger <42447585+toitzi@users.noreply.github.com> Date: Mon, 23 Sep 2024 09:35:53 +0200 Subject: [PATCH 1/2] fix(laravel): installation add authentication instructions for swagger ui in laravel --- laravel/index.md | 62 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 57 insertions(+), 5 deletions(-) diff --git a/laravel/index.md b/laravel/index.md index 35c63fbc133..66948d21aa9 100644 --- a/laravel/index.md +++ b/laravel/index.md @@ -8,9 +8,9 @@ using Laravel! With API Platform, you can: * [expose your Eloquent](#exposing-a-model) models in minutes as: - * a REST API implementing the industry-leading standards, formats and best practices: [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD)/[RDF](https://en.wikipedia.org/wiki/Resource_Description_Framework), [JSON:API](https://jsonapi.org), [HAL](https://stateless.group/hal_specification.html), and many RFCs... - * a [GraphQL](https://graphql.org/) API - * or both at the same time, with the same code! + * a REST API implementing the industry-leading standards, formats and best practices: [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD)/[RDF](https://en.wikipedia.org/wiki/Resource_Description_Framework), [JSON:API](https://jsonapi.org), [HAL](https://stateless.group/hal_specification.html), and many RFCs... + * a [GraphQL](https://graphql.org/) API + * or both at the same time, with the same code! * automatically expose an [OpenAPI](https://www.openapis.org) specification (formerly Swagger), dynamically generated from your Eloquent models and always up to date * automatically expose nice UIs and playgrounds to develop using your API ([Swagger UI](https://swagger.io/tools/swagger-ui/) and [GraphiQL](https://github.com/graphql/graphiql)) * automatically paginate your collections @@ -53,6 +53,14 @@ Open `http://127.0.0.1:8000/api/`, your API is already active and documented... ![Empty docs](images/empty-docs.png) +## Publishing the Config File and Assets + +After installing API Platform, you can publish its assets and config using the `api-platform:install` Artisan command. + +```console +php artisan api-platform:install +``` + ## Creating an Eloquent Model To discover how API Platform framework works, we will create an API to manage a bookshop. @@ -63,7 +71,7 @@ Let's start by creating a `Book` model: php artisan make:model Book ``` -By default, Laravel uses SQLite. You can open the `database/database.sqlite` file with your preferred SQLite client (PHPStorm works like a charm), create a table named `books`, and add some columns, Eloquent and API Platform will detect these columns automatically. +By default, Laravel uses SQLite. You can open the `database/database.sqlite` file with your preferred SQLite client (PhpStorm works like a charm), create a table named `books`, and add some columns, Eloquent and API Platform will detect these columns automatically. But there is a better alternative: using a migration class. @@ -553,6 +561,49 @@ It also natively supports: Follow the official instructions of the tool(s) you want to use. + +### Swagger UI and Authentication + +In the Swagger UI, you can authenticate your requests using the `Authorize` button in the top right corner. +In order to use it, you need to configure it 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 oauth2 server): + +```php +// config/api-platform.php +'swagger_ui' => [ + 'enabled' => true, + 'oauth' => [ + 'enabled' => true, + 'type' => 'oauth2', + 'flow' => 'authorizationCode', + 'tokenUrl' => '', + 'authorizationUrl' =>'', + 'refreshUrl' => '', + '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 It's sometimes convenient to enforce the use of middleware for all API routes. @@ -673,7 +724,8 @@ occurs**. ![The Next.js Progressive Web App](../symfony/images/api-platform-2.6-pwa-react.png) -API Platform also has an awesome [client generator](../create-client/index.md) able to scaffold fully working [Next.js](../create-client/nextjs.md), [Nuxt.js](../create-client/nuxt.md), [React/Redux](../create-client/react.md), [Vue.js](../create-client/vuejs.md), [Quasar](../create-client/quasar.md), and [Vuetify](../create-client/vuetify.md) Progressive Web Apps/Single Page Apps that you can easily tune and customize. The generator also supports +API Platform also has an awesome [client generator](../create-client/index.md) able to scaffold fully working [Next.js](../create-client/nextjs.md), [Nuxt.js](../create-client/nuxt.md), [React/Redux](../create-client/react.md), [Vue.js](../create-client/vuejs.md), [Quasar](../create-client/quasar.md), +and [Vuetify](../create-client/vuetify.md) Progressive Web Apps/Single Page Apps that you can easily tune and customize. The generator also supports [React Native](../create-client/react-native.md) if you prefer to leverage all capabilities of mobile devices. From 90aaa4e4c6ec85fdd62a1ad9fdfa6b202efde55f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Wed, 25 Sep 2024 16:59:11 +0200 Subject: [PATCH 2/2] Update index.md --- laravel/index.md | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/laravel/index.md b/laravel/index.md index 66948d21aa9..819a8a1a30d 100644 --- a/laravel/index.md +++ b/laravel/index.md @@ -22,7 +22,7 @@ With API Platform, you can: * 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,23 +44,25 @@ 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: -Open `http://127.0.0.1:8000/api/`, your API is already active and documented... but empty! - -![Empty docs](images/empty-docs.png) - -## Publishing the Config File and Assets +```console +php artisan api-platform:install +``` -After installing API Platform, you can publish its assets and config using the `api-platform:install` Artisan command. +If it's not already done, start the built-in web server: ```console -php artisan api-platform:install +php artisan serve ``` +Open `http://127.0.0.1:8000/api/`, your API is already active and documented... but empty! + +![Empty docs](images/empty-docs.png) + ## Creating an Eloquent Model To discover how API Platform framework works, we will create an API to manage a bookshop. @@ -126,7 +128,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 +273,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 +297,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,15 +561,14 @@ 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. -### Swagger UI and Authentication +### Login With Swagger UI -In the Swagger UI, you can authenticate your requests using the `Authorize` button in the top right corner. -In order to use it, you need to configure it in the `config/api-platform.php` file. +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: +Here is an example of how to configure API key authentication: ```php // config/api-platform.php @@ -582,7 +583,7 @@ Here is an example of how to configure API Key authentication: ] ``` -Or if you are using Laravel Passport (or any oauth2 server): +Or if you are using Laravel Passport (or any other OAuth server): ```php // config/api-platform.php