From cac9ac3563e777bed1323c9bf8ff971da1a72fe9 Mon Sep 17 00:00:00 2001 From: Alex Popa Date: Thu, 29 Feb 2024 15:57:59 +0200 Subject: [PATCH] Generate API documentation with scramble --- app/Http/Resources/IdAndNameResource.php | 6 +- app/Http/Resources/OrganisationResource.php | 4 +- composer.json | 1 + composer.lock | 173 ++++++++++++++------ config/scramble.php | 74 +++++++++ routes/api.php | 2 + 6 files changed, 207 insertions(+), 53 deletions(-) create mode 100644 config/scramble.php diff --git a/app/Http/Resources/IdAndNameResource.php b/app/Http/Resources/IdAndNameResource.php index cc80aa9..a89bfa0 100644 --- a/app/Http/Resources/IdAndNameResource.php +++ b/app/Http/Resources/IdAndNameResource.php @@ -1,5 +1,7 @@ $this->id, - 'name' => $this->name + 'id' => (int) $this->id, + 'name' => $this->name, ]; } } diff --git a/app/Http/Resources/OrganisationResource.php b/app/Http/Resources/OrganisationResource.php index aad9df3..dbea7dd 100644 --- a/app/Http/Resources/OrganisationResource.php +++ b/app/Http/Resources/OrganisationResource.php @@ -17,7 +17,7 @@ class OrganisationResource extends JsonResource public function toArray(Request $request): array { return [ - 'id' => $this->id, + 'id' => (int) $this->id, 'name' => $this->name, 'type' => $this->type, 'status' => $this->status, @@ -29,7 +29,7 @@ public function toArray(Request $request): array 'activity_counties' => IdAndNameResource::collection($this->activityCounties), 'created_at' => $this->created_at->format('Y-m-d H:i:s'), 'updated_at' => $this->updated_at->format('Y-m-d H:i:s'), - 'volunteers_count' => $this->volunteers_count, + 'volunteers_count' => (int) $this->volunteers_count, ]; } } diff --git a/composer.json b/composer.json index 57af909..c4df8f1 100644 --- a/composer.json +++ b/composer.json @@ -7,6 +7,7 @@ "require": { "php": "^8.1", "alcea/cnp": "^3.0", + "dedoc/scramble": "^0.8.5", "filament/filament": "^2.17", "filament/spatie-laravel-media-library-plugin": "^2.17", "guzzlehttp/guzzle": "^7.8", diff --git a/composer.lock b/composer.lock index 73afe8f..b3f69af 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "e9b4bb95a4e6694ebfbd2633e0586d9a", + "content-hash": "79a19b0d407e1357a655d548caaa5847", "packages": [ { "name": "akaunting/laravel-money", @@ -908,6 +908,81 @@ }, "time": "2023-08-25T16:18:39+00:00" }, + { + "name": "dedoc/scramble", + "version": "v0.8.5", + "source": { + "type": "git", + "url": "https://github.com/dedoc/scramble.git", + "reference": "cc61cc79843c6e2206dc5d0f15ae705494de8249" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/dedoc/scramble/zipball/cc61cc79843c6e2206dc5d0f15ae705494de8249", + "reference": "cc61cc79843c6e2206dc5d0f15ae705494de8249", + "shasum": "" + }, + "require": { + "illuminate/contracts": "^8.0.0|^9.0.0|^10.0.0", + "nikic/php-parser": "^4.0", + "php": "^8.1", + "phpstan/phpdoc-parser": "^1.0", + "spatie/laravel-package-tools": "^1.9.2" + }, + "require-dev": { + "doctrine/dbal": "^3.4", + "laravel/pint": "^v1.1.0", + "nunomaduro/collision": "^5.0|^v6.0", + "orchestra/testbench": "^6.0|^7.0|^8.0", + "pestphp/pest": "^1.21", + "pestphp/pest-plugin-laravel": "^1.2", + "phpunit/phpunit": "^9.5", + "spatie/pest-plugin-snapshots": "^1.1" + }, + "type": "library", + "extra": { + "laravel": { + "providers": [ + "Dedoc\\Scramble\\ScrambleServiceProvider" + ] + } + }, + "autoload": { + "psr-4": { + "Dedoc\\Scramble\\": "src", + "Dedoc\\Scramble\\Database\\Factories\\": "database/factories" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Roman Lytvynenko", + "email": "litvinenko95@gmail.com", + "role": "Developer" + } + ], + "description": "Automatic generation of API documentation for Laravel applications.", + "homepage": "https://github.com/dedoc/scramble", + "keywords": [ + "documentation", + "laravel", + "openapi" + ], + "support": { + "issues": "https://github.com/dedoc/scramble/issues", + "source": "https://github.com/dedoc/scramble/tree/v0.8.5" + }, + "funding": [ + { + "url": "https://github.com/romalytvynenko", + "type": "github" + } + ], + "time": "2023-12-02T09:58:18+00:00" + }, { "name": "dflydev/dot-access-data", "version": "v3.0.2", @@ -4773,6 +4848,53 @@ ], "time": "2023-11-12T21:59:55+00:00" }, + { + "name": "phpstan/phpdoc-parser", + "version": "1.24.3", + "source": { + "type": "git", + "url": "https://github.com/phpstan/phpdoc-parser.git", + "reference": "12f01d214f1c73b9c91fdb3b1c415e4c70652083" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/phpstan/phpdoc-parser/zipball/12f01d214f1c73b9c91fdb3b1c415e4c70652083", + "reference": "12f01d214f1c73b9c91fdb3b1c415e4c70652083", + "shasum": "" + }, + "require": { + "php": "^7.2 || ^8.0" + }, + "require-dev": { + "doctrine/annotations": "^2.0", + "nikic/php-parser": "^4.15", + "php-parallel-lint/php-parallel-lint": "^1.2", + "phpstan/extension-installer": "^1.0", + "phpstan/phpstan": "^1.5", + "phpstan/phpstan-phpunit": "^1.1", + "phpstan/phpstan-strict-rules": "^1.0", + "phpunit/phpunit": "^9.5", + "symfony/process": "^5.2" + }, + "type": "library", + "autoload": { + "psr-4": { + "PHPStan\\PhpDocParser\\": [ + "src/" + ] + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "description": "PHPDoc parser with support for nullable, intersection and generic types", + "support": { + "issues": "https://github.com/phpstan/phpdoc-parser/issues", + "source": "https://github.com/phpstan/phpdoc-parser/tree/1.24.3" + }, + "time": "2023-11-18T20:15:32+00:00" + }, { "name": "pragmarx/google2fa", "version": "v8.0.1", @@ -11648,53 +11770,6 @@ }, "time": "2023-08-12T11:01:26+00:00" }, - { - "name": "phpstan/phpdoc-parser", - "version": "1.24.3", - "source": { - "type": "git", - "url": "https://github.com/phpstan/phpdoc-parser.git", - "reference": "12f01d214f1c73b9c91fdb3b1c415e4c70652083" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/phpstan/phpdoc-parser/zipball/12f01d214f1c73b9c91fdb3b1c415e4c70652083", - "reference": "12f01d214f1c73b9c91fdb3b1c415e4c70652083", - "shasum": "" - }, - "require": { - "php": "^7.2 || ^8.0" - }, - "require-dev": { - "doctrine/annotations": "^2.0", - "nikic/php-parser": "^4.15", - "php-parallel-lint/php-parallel-lint": "^1.2", - "phpstan/extension-installer": "^1.0", - "phpstan/phpstan": "^1.5", - "phpstan/phpstan-phpunit": "^1.1", - "phpstan/phpstan-strict-rules": "^1.0", - "phpunit/phpunit": "^9.5", - "symfony/process": "^5.2" - }, - "type": "library", - "autoload": { - "psr-4": { - "PHPStan\\PhpDocParser\\": [ - "src/" - ] - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "PHPDoc parser with support for nullable, intersection and generic types", - "support": { - "issues": "https://github.com/phpstan/phpdoc-parser/issues", - "source": "https://github.com/phpstan/phpdoc-parser/tree/1.24.3" - }, - "time": "2023-11-18T20:15:32+00:00" - }, { "name": "phpunit/php-code-coverage", "version": "10.1.8", @@ -13724,5 +13799,5 @@ "php": "^8.1" }, "platform-dev": [], - "plugin-api-version": "2.6.0" + "plugin-api-version": "2.2.0" } diff --git a/config/scramble.php b/config/scramble.php new file mode 100644 index 0000000..720e3e7 --- /dev/null +++ b/config/scramble.php @@ -0,0 +1,74 @@ + 'api', + + /* + * Your API domain. By default, app domain is used. This is also a part of the default API routes + * matcher, so when implementing your own, make sure you use this config if needed. + */ + 'api_domain' => null, + + 'info' => [ + /* + * API version. + */ + 'version' => env('API_VERSION', '1'), + + /* + * Description rendered on the home page of the API documentation (`/docs/api`). + */ + 'description' => '', + ], + + /* + * Customize Stoplight Elements UI + */ + 'ui' => [ + /* + * Hide the `Try It` feature. Enabled by default. + */ + 'hide_try_it' => false, + + /* + * URL to an image that displays as a small square logo next to the title, above the table of contents. + */ + 'logo' => '', + + /* + * Use to fetch the credential policy for the Try It feature. Options are: omit, include (default), and same-origin + */ + 'try_it_credentials_policy' => 'include', + ], + + /* + * The list of servers of the API. By default, when `null`, server URL will be created from + * `scramble.api_path` and `scramble.api_domain` config variables. When providing an array, you + * will need to specify the local server URL manually (if needed). + * + * Example of non-default config (final URLs are generated using Laravel `url` helper): + * + * ```php + * 'servers' => [ + * 'Live' => 'api', + * 'Prod' => 'https://scramble.dedoc.co/api', + * ], + * ``` + */ + 'servers' => null, + + 'middleware' => [ + 'web', + RestrictedDocsAccess::class, + ], + + 'extensions' => [], +]; diff --git a/routes/api.php b/routes/api.php index ba4fea6..f507d14 100644 --- a/routes/api.php +++ b/routes/api.php @@ -17,6 +17,8 @@ | is assigned the "api" middleware group. Enjoy building your API! | */ +Gate::define('viewApiDocs', fn () => true); + Route::middleware('auth:sanctum') ->prefix('/v1') ->group(function () {