📝 fix API documentation (#2627)

app/Http/Controllers/API/v1/Controller.php

@@ -11,10 +11,7 @@
  * @OA\Info(
  * version="1.0.0 - alpha",
  * title="Träwelling API",
- * description="Träwelling user API description. This is an incomplete documentation with still many errors. The
- * API is currently not yet stable. Endpoints are still being restructured. Both the URL and the request or body
- * can be changed. Breaking changes will be announced on GitHub:
- * https://github.com/Traewelling/traewelling/blob/develop/API_CHANGELOG.md",
+ * description="Träwelling user API description. This is an incomplete documentation with still many errors. The API is currently not yet stable. Endpoints are still being restructured. Both the URL and the request or body can be changed. Breaking changes will be announced on GitHub: https://github.com/Traewelling/traewelling/blob/develop/API_CHANGELOG.md",
  * @OA\Contact(
  * email="[email protected]"
  * ),

app/Http/Controllers/API/v1/OperatorController.php

@@ -10,7 +10,7 @@ class OperatorController extends Controller
 {
  /**
  * @OA\Get(
- * path="/operators",
+ * path="/operator",
  * summary="Get a list of all operators.",
  * tags={"Checkin"},
  * @OA\Response(
@@ -23,7 +23,10 @@ class OperatorController extends Controller
  * @OA\Items(ref="#/components/schemas/OperatorResource")
  * )
  * )
- * )
+ * ),
+ * @OA\Response(response=401, description="Unauthenticated"),
+ * @OA\Response(response=403, description="Unauthorized"),
+ * @OA\Response(response=500, description="Internal Server Error")
  * )
  *
  * @return AnonymousResourceCollection

app/Http/Controllers/API/v1/ReportController.php

@@ -9,6 +9,7 @@
 use Illuminate\Auth\Access\AuthorizationException;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response;
 use Illuminate\Support\Facades\App;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Validation\Rules\Enum;
@@ -31,16 +32,16 @@ class ReportController extends Controller
  * @OA\Property(property="description", type="string", example="The status is inappropriate because...", nullable=true),
  * ),
  * ),
- * @OA\Response(response=200, description="The report was successfully created."),
+ * @OA\Response(response=201, description="The report was successfully created."),
  * @OA\Response(response=401, description="The user is not authenticated."),
  * @OA\Response(response=422, description="The given data was invalid."),
  * )
  *
  * @param Request $request
  *
- * @return JsonResponse
+ * @return Response
  */
- public function store(Request $request): JsonResponse {
+ public function store(Request $request): Response {
  $validated = $request->validate([
  'subject_type' => ['required', new Enum(ReportableSubject::class)],
  'subject_id' => ['required', 'integer', 'min:1'],
@@ -68,10 +69,7 @@ public function store(Request $request): JsonResponse {
  ]);
  }
 
- return $this->sendResponse(
- data: 'Report created.',
- code: 201
- );
+ return response()->noContent(201);
  }
 
  /**

storage/api-docs/api-docs.json

@@ -2,7 +2,7 @@
  "openapi": "3.0.0",
  "info": {
  "title": "Träwelling API",
- "description": "Träwelling user API description. This is an incomplete documentation with still many errors. The\n * API is currently not yet stable. Endpoints are still being restructured. Both the URL and the request or body\n * can be changed. Breaking changes will be announced on GitHub:\n *  https://github.com/Traewelling/traewelling/blob/develop/API_CHANGELOG.md",
+ "description": "Träwelling user API description. This is an incomplete documentation with still many errors. The API is currently not yet stable. Endpoints are still being restructured. Both the URL and the request or body can be changed. Breaking changes will be announced on GitHub: https://github.com/Traewelling/traewelling/blob/develop/API_CHANGELOG.md",
  "contact": {
  "email": "[email protected]"
  },
@@ -1247,13 +1247,13 @@
  ]
  }
  },
- "/operators": {
+ "/operator": {
  "get": {
  "tags": [
  "Checkin"
  ],
  "summary": "Get a list of all operators.",
- "operationId": "bcfcf8686980cf0fcdc751b2e13fa4f7",
+ "operationId": "5e836fb23709a92be4c939e036765dbb",
  "responses": {
  "200": {
  "description": "successful operation",
@@ -1272,6 +1272,15 @@
  }
  }
  }
+ },
+ "401": {
+ "description": "Unauthenticated"
+ },
+ "403": {
+ "description": "Unauthorized"
+ },
+ "500": {
+ "description": "Internal Server Error"
  }
  }
  }
@@ -1399,7 +1408,7 @@
  }
  },
  "responses": {
- "200": {
+ "201": {
  "description": "The report was successfully created."
  },
  "401": {
@@ -1807,7 +1816,7 @@
  "example": 11
  },
  "duration": {
- "description": "Duration in\n *  minutes",
+ "description": "Duration in minutes",
  "type": "integer",
  "example": 425
  }
@@ -1828,7 +1837,7 @@
  "example": 10
  },
  "duration": {
- "description": "Duration in\n *  minutes",
+ "description": "Duration in minutes",
  "type": "integer",
  "example": 424
  }
@@ -1850,7 +1859,7 @@
  "example": 10
  },
  "duration": {
- "description": "Duration in\n *  minutes",
+ "description": "Duration in minutes",
  "type": "integer",
  "example": 424
  }