3.1-3.6: install l5-swagger, add @OA annotations to all controllers
This commit is contained in:
1 parent
db7ce880a0
commit
afb202f333
13 files changed
+1367
-73
No files matched your search
@@ -10,8 +10,21 @@ use App\Http\Resources\PostResource;
|
||||
use App\Models\Blog\Category;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Categories", description="Blog categories")
|
||||
*/
|
||||
class CategoryController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/categories",
|
||||
* tags={"Categories"},
|
||||
* summary="Paginated list of categories",
|
||||
* @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer")),
|
||||
* @OA\Parameter(name="filter", in="query", @OA\Schema(type="string")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function index(Request $request)
|
||||
{
|
||||
$filter = $request->input('filter');
|
||||
@@ -32,12 +45,32 @@ class CategoryController extends Controller
|
||||
return CategoryResource::collection($categories);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/categories/{id}",
|
||||
* tags={"Categories"},
|
||||
* summary="Get a category by ID",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function show($id)
|
||||
{
|
||||
$category = Category::with('posts')->findOrFail($id);
|
||||
return new CategoryResource($category);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/categories/{slug}/posts",
|
||||
* tags={"Categories"},
|
||||
* summary="Get posts by category slug",
|
||||
* @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
|
||||
* @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK"),
|
||||
* @OA\Response(response=404, description="Category not found")
|
||||
* )
|
||||
*/
|
||||
public function getCategoryWithPosts(Request $request, $slug)
|
||||
{
|
||||
$category = Category::where('slug', $slug)->first();
|
||||
@@ -87,12 +120,31 @@ class CategoryController extends Controller
|
||||
], 200);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/blog/categories",
|
||||
* tags={"Categories"},
|
||||
* summary="Create a category",
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=201, description="Created")
|
||||
* )
|
||||
*/
|
||||
public function store(StoreCategoryRequest $request)
|
||||
{
|
||||
$category = Category::create($request->validated());
|
||||
return new CategoryResource($category);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Put(
|
||||
* path="/blog/categories/{id}",
|
||||
* tags={"Categories"},
|
||||
* summary="Update a category",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function update(UpdateCategoryRequest $request, $id)
|
||||
{
|
||||
$category = Category::findOrFail($id);
|
||||
@@ -100,6 +152,15 @@ class CategoryController extends Controller
|
||||
return new CategoryResource($category);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Delete(
|
||||
* path="/blog/categories/{id}",
|
||||
* tags={"Categories"},
|
||||
* summary="Delete a category",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function destroy($id)
|
||||
{
|
||||
$category = Category::findOrFail($id);
|
||||
|
||||
@@ -8,8 +8,19 @@ use App\Http\Resources\PostResource;
|
||||
use App\Models\Blog\Category;
|
||||
use App\Models\Blog\Post;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Blog Home", description="Blog homepage aggregated data")
|
||||
*/
|
||||
class HomeController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/homepage",
|
||||
* tags={"Blog Home"},
|
||||
* summary="Get homepage data: latest posts, categories, most viewed, random",
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function index()
|
||||
{
|
||||
$latestPosts = Post::with(['category', 'tags', 'author'])
|
||||
|
||||
@@ -9,8 +9,25 @@ use App\Http\Resources\PostResource;
|
||||
use App\Models\Blog\Post;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Posts", description="Blog post management")
|
||||
*/
|
||||
class PostController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/posts",
|
||||
* tags={"Posts"},
|
||||
* summary="Paginated list of posts",
|
||||
* @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer")),
|
||||
* @OA\Parameter(name="category", in="query", @OA\Schema(type="string")),
|
||||
* @OA\Parameter(name="tag", in="query", @OA\Schema(type="string")),
|
||||
* @OA\Parameter(name="search", in="query", @OA\Schema(type="string")),
|
||||
* @OA\Parameter(name="sort_field", in="query", @OA\Schema(type="string")),
|
||||
* @OA\Parameter(name="sort_direction", in="query", @OA\Schema(type="string", enum={"asc","desc"})),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function index(Request $request)
|
||||
{
|
||||
$filters = $request->only(['category', 'tag', 'search', 'author', 'published']);
|
||||
@@ -29,6 +46,15 @@ class PostController extends Controller
|
||||
return PostResource::collection($posts);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/posts/{slug}",
|
||||
* tags={"Posts"},
|
||||
* summary="Get a single post by slug with related posts",
|
||||
* @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function show($slug)
|
||||
{
|
||||
$post = Post::with(['category', 'tags', 'author', 'relatedPosts.category', 'relatedPosts.tags', 'relatedPosts.author'])
|
||||
@@ -41,6 +67,15 @@ class PostController extends Controller
|
||||
], 200);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/blog/posts",
|
||||
* tags={"Posts"},
|
||||
* summary="Create a post",
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=201, description="Created")
|
||||
* )
|
||||
*/
|
||||
public function store(StorePostRequest $request)
|
||||
{
|
||||
$post = Post::create($request->validated());
|
||||
@@ -52,6 +87,16 @@ class PostController extends Controller
|
||||
return new PostResource($post->load(['category', 'tags', 'author']));
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Put(
|
||||
* path="/blog/posts/{id}",
|
||||
* tags={"Posts"},
|
||||
* summary="Update a post",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function update(UpdatePostRequest $request, $id)
|
||||
{
|
||||
$post = Post::findOrFail($id);
|
||||
@@ -64,6 +109,15 @@ class PostController extends Controller
|
||||
return new PostResource($post->load(['category', 'tags', 'author']));
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Delete(
|
||||
* path="/blog/posts/{id}",
|
||||
* tags={"Posts"},
|
||||
* summary="Delete a post",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function destroy($id)
|
||||
{
|
||||
$post = Post::findOrFail($id);
|
||||
|
||||
@@ -9,26 +9,65 @@ use App\Http\Resources\TagResource;
|
||||
use App\Models\Blog\Tag;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Tags", description="Blog tag management")
|
||||
*/
|
||||
class TagController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/tags",
|
||||
* tags={"Tags"},
|
||||
* summary="Paginated list of tags",
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function index(Request $request)
|
||||
{
|
||||
$tags = Tag::with('posts')->paginate(10);
|
||||
return TagResource::collection($tags);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/blog/tags/{id}",
|
||||
* tags={"Tags"},
|
||||
* summary="Get a tag by ID",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function show($id)
|
||||
{
|
||||
$tag = Tag::with('posts')->findOrFail($id);
|
||||
return new TagResource($tag);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/blog/tags",
|
||||
* tags={"Tags"},
|
||||
* summary="Create a tag",
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=201, description="Created")
|
||||
* )
|
||||
*/
|
||||
public function store(StoreTagRequest $request)
|
||||
{
|
||||
$tag = Tag::create($request->validated());
|
||||
return new TagResource($tag);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Put(
|
||||
* path="/blog/tags/{id}",
|
||||
* tags={"Tags"},
|
||||
* summary="Update a tag",
|
||||
* @OA\Parameter(name="id", in="path", required=True, @OA\Schema(type="integer")),
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function update(UpdateTagRequest $request, $id)
|
||||
{
|
||||
$tag = Tag::findOrFail($id);
|
||||
@@ -36,6 +75,15 @@ class TagController extends Controller
|
||||
return new TagResource($tag);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Delete(
|
||||
* path="/blog/tags/{id}",
|
||||
* tags={"Tags"},
|
||||
* summary="Delete a tag",
|
||||
* @OA\Parameter(name="id", in="path", required=True, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function destroy($id)
|
||||
{
|
||||
$tag = Tag::findOrFail($id);
|
||||
|
||||
@@ -7,26 +7,65 @@ use App\Http\Requests\Website\StoreAboutMeRequest;
|
||||
use App\Http\Requests\Website\UpdateAboutMeRequest;
|
||||
use App\Models\Website\AboutMe;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="About Me", description="About Me section endpoints")
|
||||
*/
|
||||
class AboutMeController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/about-me",
|
||||
* tags={"About Me"},
|
||||
* summary="Get the first About Me entry with skills",
|
||||
* @OA\Response(response=200, description="OK", @OA\JsonContent(ref="#/components/schemas/AboutMe"))
|
||||
* )
|
||||
*/
|
||||
public function index()
|
||||
{
|
||||
$aboutMe = AboutMe::with('skills')->first();
|
||||
return response()->json($aboutMe);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/about-me/{id}",
|
||||
* tags={"About Me"},
|
||||
* summary="Get a specific About Me entry",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function show($id)
|
||||
{
|
||||
$aboutMe = AboutMe::with('skills')->findOrFail($id);
|
||||
return response()->json($aboutMe);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/website/about-me",
|
||||
* tags={"About Me"},
|
||||
* summary="Create an About Me entry",
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=201, description="Created")
|
||||
* )
|
||||
*/
|
||||
public function store(StoreAboutMeRequest $request)
|
||||
{
|
||||
$aboutMe = AboutMe::create($request->validated());
|
||||
return response()->json($aboutMe, 201);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Put(
|
||||
* path="/website/about-me/{id}",
|
||||
* tags={"About Me"},
|
||||
* summary="Update an About Me entry",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function update(UpdateAboutMeRequest $request, $id)
|
||||
{
|
||||
$aboutMe = AboutMe::findOrFail($id);
|
||||
@@ -34,12 +73,32 @@ class AboutMeController extends Controller
|
||||
return response()->json($aboutMe);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Delete(
|
||||
* path="/website/about-me/{id}",
|
||||
* tags={"About Me"},
|
||||
* summary="Delete an About Me entry",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=204, description="No Content")
|
||||
* )
|
||||
*/
|
||||
public function destroy($id)
|
||||
{
|
||||
AboutMe::destroy($id);
|
||||
return response()->json(null, 204);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/about-me/{id}/translation/{locale}",
|
||||
* tags={"About Me"},
|
||||
* summary="Get localized About Me with skills",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Parameter(name="locale", in="path", required=true, @OA\Schema(type="string", enum={"fa","en"})),
|
||||
* @OA\Response(response=200, description="OK", @OA\JsonContent(ref="#/components/schemas/AboutMe")),
|
||||
* @OA\Response(response=404, description="Translation not found")
|
||||
* )
|
||||
*/
|
||||
public function getTranslation($id, $locale)
|
||||
{
|
||||
$aboutMe = AboutMe::with('skills')->findOrFail($id);
|
||||
|
||||
@@ -8,8 +8,22 @@ use App\Http\Requests\Website\UpdateProjectRequest;
|
||||
use App\Models\Website\Project;
|
||||
use App\Models\Website\ProjectCategory;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Projects", description="Projects section endpoints")
|
||||
*/
|
||||
class ProjectController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/projects/translation/{locale}",
|
||||
* tags={"Projects"},
|
||||
* summary="List projects and categories in a locale",
|
||||
* @OA\Parameter(name="locale", in="path", required=true, @OA\Schema(type="string", enum={"fa","en"})),
|
||||
* @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer")),
|
||||
* @OA\Parameter(name="sort", in="query", @OA\Schema(type="string", enum={"asc","desc"})),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function index($locale): \Illuminate\Http\JsonResponse
|
||||
{
|
||||
$perPage = request()->query('per_page', 10);
|
||||
@@ -48,6 +62,15 @@ class ProjectController extends Controller
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/website/projects",
|
||||
* tags={"Projects"},
|
||||
* summary="Create a project",
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=201, description="Created")
|
||||
* )
|
||||
*/
|
||||
public function store(StoreProjectRequest $request)
|
||||
{
|
||||
$project = Project::create($request->only(['category_id', 'image1', 'image2']));
|
||||
@@ -61,6 +84,16 @@ class ProjectController extends Controller
|
||||
return response()->json($project, 201);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/projects/{id}/translation/{locale}",
|
||||
* tags={"Projects"},
|
||||
* summary="Get a single project translation",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Parameter(name="locale", in="path", required=true, @OA\Schema(type="string", enum={"fa","en"})),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function show($id, $locale)
|
||||
{
|
||||
$project = Project::with('category')->findOrFail($id);
|
||||
@@ -68,7 +101,7 @@ class ProjectController extends Controller
|
||||
$formattedProject = [
|
||||
'id' => $project->id,
|
||||
'title' => $project->getTranslation('title', $locale),
|
||||
'category' => $project->category?->getTranslation('title', 'fa'),
|
||||
'category' => $project->category?->getTranslation('title', $locale),
|
||||
'images' => [
|
||||
['src' => $project->image1, 'position' => '1', 'zIndex' => 1],
|
||||
['src' => $project->image2, 'position' => '2', 'zIndex' => 2],
|
||||
@@ -80,6 +113,16 @@ class ProjectController extends Controller
|
||||
return response()->json(['project' => $formattedProject]);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Put(
|
||||
* path="/website/projects/{id}",
|
||||
* tags={"Projects"},
|
||||
* summary="Update a project",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\RequestBody(@OA\MediaType(mediaType="application/json")),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function update(UpdateProjectRequest $request, $id)
|
||||
{
|
||||
$project = Project::findOrFail($id);
|
||||
@@ -98,6 +141,15 @@ class ProjectController extends Controller
|
||||
return response()->json($project);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Delete(
|
||||
* path="/website/projects/{id}",
|
||||
* tags={"Projects"},
|
||||
* summary="Delete a project",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Response(response=204, description="No Content")
|
||||
* )
|
||||
*/
|
||||
public function destroy($id)
|
||||
{
|
||||
Project::destroy($id);
|
||||
|
||||
@@ -5,8 +5,20 @@ namespace App\Http\Controllers\Api\Website;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Models\Website\Service;
|
||||
|
||||
/**
|
||||
* @OA\Tag(name="Services", description="Services section endpoints")
|
||||
*/
|
||||
class ServiceController extends Controller
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/services/{locale}",
|
||||
* tags={"Services"},
|
||||
* summary="List all services in a given locale",
|
||||
* @OA\Parameter(name="locale", in="path", required=true, @OA\Schema(type="string", enum={"fa","en"})),
|
||||
* @OA\Response(response=200, description="OK", @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/Service")))
|
||||
* )
|
||||
*/
|
||||
public function index($locale)
|
||||
{
|
||||
$services = Service::all();
|
||||
@@ -26,6 +38,16 @@ class ServiceController extends Controller
|
||||
return response()->json($response);
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/website/services/{id}/translation/{locale}",
|
||||
* tags={"Services"},
|
||||
* summary="Get a single service translation",
|
||||
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
||||
* @OA\Parameter(name="locale", in="path", required=true, @OA\Schema(type="string", enum={"fa","en"})),
|
||||
* @OA\Response(response=200, description="OK")
|
||||
* )
|
||||
*/
|
||||
public function showTranslation($id, $locale)
|
||||
{
|
||||
$service = Service::findOrFail($id);
|
||||
|
||||
Reference in new issue
Block a user