Skip to content

Commit ae25ccb

Browse files
MrKrisKrisuMrKrisKrisu
authored
📝 improve api documentation (#2477)
1 parent 6945845 commit ae25ccb

File tree

5 files changed

+75
-212
lines changed

5 files changed

+75
-212
lines changed

‎.env.example

+5
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,8 @@ FULL_POINTS_MIN_AFTER=10
9090
# Here you can set the default values for the privacy settings
9191
PRIVACY_ACCOUNT_DELETION_SEND_NOTIFICATION=false
9292
PRIVACY_ACCOUNT_DELETION_DELETE_ACCOUNT=false
93+
94+
# For local development, we recommend to always generate the swagger documentation.
95+
# This will make sure that the documentation is always up to date, if you access it via /api/documentation.
96+
# So you doesn't forget to publish the documentation after changing the API.
97+
L5_SWAGGER_GENERATE_ALWAYS=true

‎app/Http/Controllers/API/v1/EventController.php

+3-3
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ class EventController extends Controller
3737
* @OA\Property (
3838
* property="data",
3939
* type="object",
40-
* ref="#/components/schemas/Event"
40+
* ref="#/components/schemas/EventResource"
4141
* )
4242
* )
4343
* ),
@@ -178,7 +178,7 @@ public static function statuses(string $slug): AnonymousResourceCollection {
178178
* property="data",
179179
* type="array",
180180
* @OA\Items(
181-
* ref="#/components/schemas/Event"
181+
* ref="#/components/schemas/EventResource"
182182
* )
183183
* )
184184
* )
@@ -283,7 +283,7 @@ public function suggest(Request $request): JsonResponse {
283283
* property="data",
284284
* type="array",
285285
* @OA\Items(
286-
* ref="#/components/schemas/Event"
286+
* ref="#/components/schemas/EventResource"
287287
* )
288288
* )
289289
* )

‎app/Http/Resources/EventResource.php

+15-7
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,23 @@
55
use Illuminate\Http\Request;
66
use Illuminate\Http\Resources\Json\JsonResource;
77

8+
/**
9+
* @OA\Schema(
10+
* title="Event",
11+
* @OA\Property(property="id", type="integer", example=39),
12+
* @OA\Property(property="name", type="string", example="9-Euro-Ticket"),
13+
* @OA\Property(property="slug", type="string", example="9_euro_ticket"),
14+
* @OA\Property(property="hashtag", type="string", example="NeunEuroTicket"),
15+
* @OA\Property(property="host", type="string", example="9-Euro-Ticket GmbH"),
16+
* @OA\Property(property="url", type="string", example="https://9-euro-ticket.de"),
17+
* @OA\Property(property="begin", type="string", format="date-time", example="2022-01-01T00:00:00+00:00"),
18+
* @OA\Property(property="end", type="string", format="date-time", example="2022-01-02T00:00:00+00:00"),
19+
* @OA\Property(property="station", type="string", ref="#/components/schemas/Station")
20+
* )
21+
*/
822
class EventResource extends JsonResource
923
{
10-
/**
11-
* Transform the resource into an array.
12-
*
13-
* @param Request $request
14-
*
15-
* @return array
16-
*/
24+
1725
public function toArray($request): array {
1826
return [
1927
"id" => $this->id,

‎app/Virtual/Models/Event.php

-118
This file was deleted.

‎storage/api-docs/api-docs.json

+52-84
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
"description": "Production Server"
1919
},
2020
{
21-
"url": "https://traewelling.de/api/v1",
21+
"url": "http://localhost:8000/api/v1",
2222
"description": "This instance"
2323
}
2424
],
@@ -164,7 +164,7 @@
164164
"schema": {
165165
"properties": {
166166
"data": {
167-
"$ref": "#/components/schemas/Event"
167+
"$ref": "#/components/schemas/EventResource"
168168
}
169169
},
170170
"type": "object"
@@ -346,7 +346,7 @@
346346
"data": {
347347
"type": "array",
348348
"items": {
349-
"$ref": "#/components/schemas/Event"
349+
"$ref": "#/components/schemas/EventResource"
350350
}
351351
}
352352
},
@@ -442,7 +442,7 @@
442442
"data": {
443443
"type": "array",
444444
"items": {
445-
"$ref": "#/components/schemas/Event"
445+
"$ref": "#/components/schemas/EventResource"
446446
}
447447
}
448448
},
@@ -4369,6 +4369,49 @@
43694369
"name": "Station"
43704370
}
43714371
},
4372+
"EventResource": {
4373+
"title": "Event",
4374+
"properties": {
4375+
"id": {
4376+
"type": "integer",
4377+
"example": 39
4378+
},
4379+
"name": {
4380+
"type": "string",
4381+
"example": "9-Euro-Ticket"
4382+
},
4383+
"slug": {
4384+
"type": "string",
4385+
"example": "9_euro_ticket"
4386+
},
4387+
"hashtag": {
4388+
"type": "string",
4389+
"example": "NeunEuroTicket"
4390+
},
4391+
"host": {
4392+
"type": "string",
4393+
"example": "9-Euro-Ticket GmbH"
4394+
},
4395+
"url": {
4396+
"type": "string",
4397+
"example": "https://9-euro-ticket.de"
4398+
},
4399+
"begin": {
4400+
"type": "string",
4401+
"format": "date-time",
4402+
"example": "2022-01-01T00:00:00+00:00"
4403+
},
4404+
"end": {
4405+
"type": "string",
4406+
"format": "date-time",
4407+
"example": "2022-01-02T00:00:00+00:00"
4408+
},
4409+
"station": {
4410+
"$ref": "#/components/schemas/Station"
4411+
}
4412+
},
4413+
"type": "object"
4414+
},
43724415
"AutocompleteStation": {
43734416
"title": "AutocompleteStation",
43744417
"description": "shortened train station model",
@@ -4571,76 +4614,6 @@
45714614
"name": "Client"
45724615
}
45734616
},
4574-
"Event": {
4575-
"title": "Event",
4576-
"description": "Event model",
4577-
"properties": {
4578-
"id": {
4579-
"title": "ID",
4580-
"description": "ID",
4581-
"type": "integer",
4582-
"format": "int64",
4583-
"example": 39
4584-
},
4585-
"name": {
4586-
"title": "name",
4587-
"description": "Name of event",
4588-
"type": "string",
4589-
"example": "9-Euro-Ticket"
4590-
},
4591-
"slug": {
4592-
"title": "slug",
4593-
"description": "URL-Slug for event",
4594-
"type": "string",
4595-
"example": "9_euro_ticket"
4596-
},
4597-
"hashtag": {
4598-
"title": "hashtag",
4599-
"description": "social media hashtag for event",
4600-
"type": "string",
4601-
"example": "NeunEuroTicket"
4602-
},
4603-
"host": {
4604-
"title": "host",
4605-
"description": "host of the event",
4606-
"example": "Die Bundesregierung"
4607-
},
4608-
"url": {
4609-
"title": "url",
4610-
"description": "external URL for this event",
4611-
"type": "string",
4612-
"example": "https://www.bundesregierung.de/breg-de/aktuelles/faq-9-euro-ticket-2028756"
4613-
},
4614-
"begin": {
4615-
"title": "begin",
4616-
"description": "Timestamp for the start of the event",
4617-
"example": "2022-06-01T00:00:00+02:00"
4618-
},
4619-
"end": {
4620-
"title": "end",
4621-
"description": "Timestamp for the end of the event",
4622-
"example": "2022-08-31T23:59:00+02:00"
4623-
},
4624-
"station": {
4625-
"title": "station",
4626-
"description": "nearest station for this event (nullable)",
4627-
"type": "object",
4628-
"nullable": "true",
4629-
"anyOf": [
4630-
{
4631-
"$ref": "#/components/schemas/Station"
4632-
},
4633-
{
4634-
"type": "'null'"
4635-
}
4636-
]
4637-
}
4638-
},
4639-
"type": "object",
4640-
"xml": {
4641-
"name": "Event"
4642-
}
4643-
},
46444617
"EventDetails": {
46454618
"title": "EventDetails",
46464619
"description": "Statistics/Details for Event",
@@ -5175,14 +5148,9 @@
51755148
"$ref": "#/components/schemas/Trip"
51765149
},
51775150
"event": {
5178-
"oneOf": [
5179-
{
5180-
"$ref": "#/components/schemas/Event"
5181-
}
5182-
],
5183-
"nullable": true,
51845151
"title": "event",
5185-
"description": "Event model (nullable)"
5152+
"description": "Event model (nullable)",
5153+
"nullable": true
51865154
}
51875155
},
51885156
"type": "object",
@@ -5956,9 +5924,9 @@
59565924
"scheme": "https",
59575925
"flows": {
59585926
"authorizationCode": {
5959-
"authorizationUrl": "https://traewelling.de/oauth/authorize",
5960-
"tokenUrl": "https://traewelling.de/oauth/token",
5961-
"refreshUrl": "https://traewelling.de/auth/refresh",
5927+
"authorizationUrl": "http://localhost:8000/oauth/authorize",
5928+
"tokenUrl": "http://localhost:8000/oauth/token",
5929+
"refreshUrl": "http://localhost:8000/auth/refresh",
59625930
"scopes": {
59635931
"read-statuses": "see all statuses",
59645932
"read-notifications": "see your notifications",

0 commit comments

Comments
 (0)