mirror of
https://github.com/HolgerHatGarKeineNode/einundzwanzig-app.git
synced 2026-06-11 02:50:29 +00:00
✨ **Enhance API functionality and localizations**
- 🌐 Added API documentation annotations for multiple controllers (Meetups, Cities, Countries, Courses, Highscores, Venues), improving public and developer-facing endpoint clarity. - ➕ Integrated and configured the `dedoc/scramble` package for automated OpenAPI documentation generation. - 🔒 Excluded internal routes and actions from API documentation using `ExcludeRouteFromDocs` attributes. - 🌍 Added new localization keys for API Token features across multiple languages (`lv`, `es`, etc.). - 🛠️ Introduced `Group`, `Response`, and `QueryParameter` attributes for better request descriptions and structured documentation. - 🚀 Enhanced functionality for listing operations in controllers with filters and query parameters like `search` and `selected`.
This commit is contained in:
HolgerHatGarKeineNode
@@ -0,0 +1,198 @@
|
||||
<?php
|
||||
|
||||
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
|
||||
use Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy;
|
||||
use Dedoc\Scramble\Support\Generator\SecurityScheme;
|
||||
|
||||
return [
|
||||
/*
|
||||
* Which routes to document. String or array form; use Scramble::routes() for custom selection.
|
||||
*
|
||||
* 'api_path' => [
|
||||
* 'include' => 'api',
|
||||
* 'exclude' => ['api/internal'],
|
||||
* ],
|
||||
*
|
||||
* Without *, patterns match path segments (api matches api and api/users, not apiary).
|
||||
* With *, Str::is is used (e.g. api/v*).
|
||||
*
|
||||
* One static include → default server is /{include} and paths are stripped (/users).
|
||||
* Multiple includes or wildcards → server defaults to / and paths stay full (/api/users).
|
||||
* Override with `servers`, or use Scramble::registerApi() for separate bases.
|
||||
*/
|
||||
'api_path' => '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,
|
||||
|
||||
/*
|
||||
* The path where your OpenAPI specification will be exported.
|
||||
*/
|
||||
'export_path' => 'api.json',
|
||||
|
||||
'info' => [
|
||||
/*
|
||||
* API version.
|
||||
*/
|
||||
'version' => env('API_VERSION', '1.0.0'),
|
||||
|
||||
/*
|
||||
* Description rendered on the home page of the API documentation (`/docs/api`).
|
||||
*/
|
||||
'description' => <<<'MARKDOWN'
|
||||
Willkommen bei der **Einundzwanzig API** – der öffentlichen Schnittstelle der
|
||||
[Einundzwanzig](https://einundzwanzig.space) Bitcoin-Community-Plattform.
|
||||
|
||||
Über diese API erreichst du die Daten der dezentralen deutschsprachigen Bitcoin-Bewegung:
|
||||
Meetups und ihre Termine, Kurse und Kurs-Events, Referenten, Veranstaltungsorte sowie die
|
||||
Geo-Daten für die Community-Karte.
|
||||
|
||||
## Authentifizierung
|
||||
|
||||
Die meisten **Lese-Endpunkte** sind öffentlich und benötigen kein Token.
|
||||
|
||||
**Schreibende Endpunkte** (Kurse & Kurs-Events anlegen/aktualisieren) erfordern ein
|
||||
persönliches Zugriffstoken. Erzeuge dir eines unter
|
||||
*Einstellungen → API Tokens* und sende es als Bearer-Token:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <dein-token>
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Öffentliche Endpunkte sind auf **60 Anfragen/Minute** begrenzt, das Einreichen von
|
||||
Highscores zusätzlich auf **10 Anfragen/Minute**.
|
||||
MARKDOWN,
|
||||
],
|
||||
|
||||
'ui' => [
|
||||
'title' => 'Einundzwanzig API',
|
||||
],
|
||||
|
||||
'renderer' => 'scalar',
|
||||
|
||||
'renderers' => [
|
||||
/*
|
||||
* Stoplight Elements config options: https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
|
||||
*/
|
||||
'elements' => [
|
||||
'view' => 'scramble::docs',
|
||||
'theme' => 'light',
|
||||
'hideTryIt' => false,
|
||||
'hideSchemas' => false,
|
||||
'logo' => '',
|
||||
'tryItCredentialsPolicy' => 'include',
|
||||
'layout' => 'responsive',
|
||||
'router' => 'hash',
|
||||
],
|
||||
/*
|
||||
* Scalar API reference config options: https://scalar.com/products/api-references/configuration
|
||||
*/
|
||||
'scalar' => [
|
||||
'view' => 'scramble::scalar',
|
||||
'cdn' => 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
|
||||
'theme' => 'laravel',
|
||||
'proxyUrl' => 'https://proxy.scalar.com',
|
||||
'darkMode' => true,
|
||||
'showDeveloperTools' => 'never',
|
||||
'agent' => ['disabled' => true],
|
||||
'credentials' => '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' => [
|
||||
'Production' => 'https://einundzwanzig.space/api',
|
||||
'Local' => 'api',
|
||||
],
|
||||
|
||||
/**
|
||||
* Determines how Scramble stores the descriptions of enum cases.
|
||||
* Available options:
|
||||
* - 'description' – Case descriptions are stored as the enum schema's description using table formatting.
|
||||
* - 'extension' – Case descriptions are stored in the `x-enumDescriptions` enum schema extension.
|
||||
*
|
||||
* @see https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-enum-descriptions
|
||||
* - false - Case descriptions are ignored.
|
||||
*/
|
||||
'enum_cases_description_strategy' => 'description',
|
||||
|
||||
/**
|
||||
* Determines how Scramble stores the names of enum cases.
|
||||
* Available options:
|
||||
* - 'names' – Case names are stored in the `x-enumNames` enum schema extension.
|
||||
* - 'varnames' - Case names are stored in the `x-enum-varnames` enum schema extension.
|
||||
* - false - Case names are not stored.
|
||||
*/
|
||||
'enum_cases_names_strategy' => false,
|
||||
|
||||
/**
|
||||
* When Scramble encounters deep objects in query parameters, it flattens the parameters so the generated
|
||||
* OpenAPI document correctly describes the API. Flattening deep query parameters is relevant until
|
||||
* OpenAPI 3.2 is released and query string structure can be described properly.
|
||||
*
|
||||
* For example, this nested validation rule describes the object with `bar` property:
|
||||
* `['foo.bar' => ['required', 'int']]`.
|
||||
*
|
||||
* When `flatten_deep_query_parameters` is `true`, Scramble will document the parameter like so:
|
||||
* `{"name":"foo[bar]", "schema":{"type":"int"}, "required":true}`.
|
||||
*
|
||||
* When `flatten_deep_query_parameters` is `false`, Scramble will document the parameter like so:
|
||||
* `{"name":"foo", "schema": {"type":"object", "properties":{"bar":{"type": "int"}}, "required": ["bar"]}, "required":true}`.
|
||||
*/
|
||||
'flatten_deep_query_parameters' => true,
|
||||
|
||||
'middleware' => [
|
||||
'web',
|
||||
RestrictedDocsAccess::class,
|
||||
],
|
||||
|
||||
'extensions' => [],
|
||||
|
||||
/*
|
||||
* Automatically document API security (OpenAPI `security` / `securitySchemes`) based on route
|
||||
* middleware.
|
||||
*
|
||||
* Disabled by default. Uncomment the line below to enable `MiddlewareAuthSecurityStrategy`.
|
||||
* When at least one documented route uses middleware matching the configured patterns (by default
|
||||
* `auth` and `auth:*`), bearer auth is applied globally. Routes without matching middleware are
|
||||
* marked as public (`security: []`).
|
||||
*
|
||||
* Set to `null` explicitly to disable. If you already configure security manually via
|
||||
* `afterOpenApiGenerated` / `extendOpenApi`, keep this disabled to avoid duplicate schemes.
|
||||
*
|
||||
* Customize with a class-string or [class, options]:
|
||||
*
|
||||
* 'security_strategy' => [
|
||||
* \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,
|
||||
* [
|
||||
* 'middleware' => ['auth', 'auth:*'],
|
||||
* 'scheme' => \Dedoc\Scramble\Support\Generator\SecurityScheme::http('bearer'),
|
||||
* ],
|
||||
* ],
|
||||
*/
|
||||
'security_strategy' => [
|
||||
MiddlewareAuthSecurityStrategy::class,
|
||||
[
|
||||
'middleware' => ['auth', 'auth:*'],
|
||||
'scheme' => SecurityScheme::http('bearer'),
|
||||
],
|
||||
],
|
||||
];
|
||||
Reference in New Issue
Block a user