Laravel 11 Swagger

✅ 1. Laravel 11 프로젝트 준비

Laravel 11 프로젝트가 없다면 새로 생성합니다:

composer create-project laravel/laravel my-api-app
cd my-api-app

---

✅ 2. Swagger 패키지 설치 (L5-Swagger)

composer require darkaonline/l5-swagger

---

✅ 3. 설정 파일 게시 (Laravel 11에서는 Config가 없을 수 있으므로 명시적으로 게시)

php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"

 

이 명령으로 config/l5-swagger.php 파일이 생성됩니다.

---

✅ 4. Swagger UI 접근 설정

기본적으로 Swagger UI는 /api/documentation 경로에서 접근할 수 있습니다.

routes/web.php 또는 routes/api.php에서 다음과 같이 미들웨어 설정이 충돌하지 않도록 조정할 수 있습니다.

Route::get('/api/documentation', function () {
    return redirect('/api/documentation/index.html');
});

또는 Swagger 미들웨어가 막히지 않도록 web.php 또는 api.php 내에서 예외 처리 필요.

---

✅ 5. API 주석 작성 (Swagger 어노테이션)

컨트롤러 메서드에 주석으로 Swagger 문서 생성:

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="Get list of users",
 *     tags={"Users"},
 *     @OA\Response(
 *         response=200,
 *         description="Successful operation"
 *     )
 * )
 */
public function index()
{
    return User::all();
}

---

✅ 6. Swagger 문서 생성

php artisan l5-swagger:generate

이 명령을 실행하면 public/docs 디렉토리에 Swagger 문서가 생성됩니다.

---

✅ 7. Swagger UI 접속

브라우저에서 아래 주소로 접속:

http://localhost:8000/api/documentation

---

✅ 8. 참고: 필요 패키지

composer.json에 자동으로 포함되지 않으면 다음도 설치 필요할 수 있습니다:

composer require zircote/swagger-php

---

🔧 추가 설정 (선택 사항)

config/l5-swagger.php에서 다양한 설정 가능:

• 기본 경로 변경
• 보안 스키마 정의 (JWT 토큰 등)
• 모델 문서화 등

---

🤝 도움이 될 만한 Swagger 주석 예시

/**
 * @OA\Post(
 *     path="/api/login",
 *     summary="User login",
 *     tags={"Auth"},
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(
 *             required={"email", "password"},
 *             @OA\Property(property="email", type="string", format="email"),
 *             @OA\Property(property="password", type="string", format="password")
 *         )
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Login successful"
 *     ),
 *     @OA\Response(
 *         response=401,
 *         description="Invalid credentials"
 *     )
 * )
 */