[Laravel] 라라벨에 swagger 적용하기

기본 세팅

1. 프로젝트에 swagger 설치하기

composer require "darkaonline/l5-swagger"

 

2. config 파일 생성

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

 

3. provider 설정

config/app.php 파일 수정

'providers' => [
	/*
    * Laravel Framework Service Providers...*/
    L5Swagger\L5SwaggerServiceProvider::class,
]

 

4. config 설정

config/I5-swagger.php 파일 수정

'api' => [
	'title' => {원하는 제목}
],

'routes' => [
	/*
    * Route for accessing api documentation interface
    */
    'api' => 'api/documentation',
],

'defaults' => [
	'routes' => [
    	/*
         * Route for accessing parsed swagger annotations.
         */
         'docs' => 'docs',

 

5. 컨트롤러 파일중 하나에 Annotation으로 기술

 /**
 * @OA\Info(
 *     title="TEST API",
 *     version="1.0",
 *     description="TEST API Document"
 * )
 **/

 

6. 적용 (터미널)

php artisan l5-swagger:generate

 

7. http://127.0.0.1:8000/api/documentation# 으로 접속

 

---

 

내용 작성하기

- 컨트롤러 안의 public function 위에 작성해야 한다.

 

@OA\{Get | Post | Put | Delete}

* @OA\Get (
*     path="/api/v1/test/{id}",
*     operationId="testAPI",
*     tags={"테스트"},
*     summary="테스트 api",
*     description="테스트용 작성",
*     security={{"bearer_token":{}}},
*     @OA\Parameter(
*          name="id",
*          description="파라미터",
*          in="path",
*          required=true,
*          example="test"
*          @OA\Schema(type="string")
*     ),
*     @OA\Response(
*          response="200",
*          description= "성공"
*      ),
*     @OA\Response(
*          response="400",
*          description= "실패"
*      ),
*     security={{"api_key_security":{}}}
* )

 

@OA\Parameter

- Get 방식 전송

*     @OA\Parameter(
*          name="test_parameter",
*          description="파라미터",
*          in="path",
*          required=true,
*          example="test"
*          @OA\Schema(type="string")
*     )

- Header로 전송

*     @OA\Parameter(
*          name="test_parameter",
*          description="파라미터",
*          in="header",
*          required=true,
*          example="test"
*          @OA\Schema(type="string")
*     )

 

@OA\RequestBody

- json형식

*     @OA\RequestBody(
*          @OA\MediaType(e
*              mediaType="application/json",
*              @OA\Schema(
*                  @OA\Property(property="image_file", type="int", description="회원 번호", example=1),
*                  @OA\Property(property="name", type="string", description="회원 이름", example="김김김")
*              )
*          )
*      )

- form-data 형식

 *     @OA\RequestBody(
 *          @OA\MediaType(
 *              mediaType="multipart/form-data",
 *              @OA\Schema(
 *                  @OA\Property(property="image_file", type="file", description="이미지 파일", format="file")
 *              )
 *          )
 *      )

 

@OA\Response

- 문자 출력

 *     @OA\Response(
 *          response="400",
 *          description= "실패"
 *      )

- 배열 출력

 *     @OA\Response(
 *          response="200",
 *          description= "성공",
 *          @OA\JsonContent(
 *              @OA\Property(property="result", type="array",
 *                  @OA\Items(
 *                      @OA\Property(property="state", type="string", description="상태", example=true),
 *                      @OA\Property(property="code", type="int", description="코드", example=2000),
 *                      @OA\Property(property="descMsg", type="string", description="메세지", example="SUCCESS"),
 *                  ),
 *              ),
 *              @OA\Property(property="data", type="string", description="데이터", example="이미지 url"),
 *          )
 *      )

- 객체 출력

 *     @OA\Response(
 *          response="200",
 *          description= "성공",
 *          @OA\JsonContent(
 *              @OA\Property(property="result", type="object",
 *                      @OA\Property(property="state", type="string", description="상태", example=true),
 *                      @OA\Property(property="code", type="int", description="코드", example=2000),
 *                      @OA\Property(property="descMsg", type="string", description="메세지", example="SUCCESS"),
 *              ),
 *              @OA\Property(property="data", type="string", description="데이터", example="이미지 url"),
 *          )
 *      )

 

---

 

laravel bearer_token 인증

comfig/I5-swagger.php 수정

'securityDefinitions' => [
    'securitySchemes' => [
    	'bearer_token' => [ // Unique name of security
        	'type' => 'apiKey', // Valid values are "basic", "apiKey" or "oauth2".
            'description' => 'Enter token in format (Bearer <token>)',
            'name' => 'Authorization', // The name of the header or query parameter to be used.
            'in' => 'header', // The location of the API key. Valid values are "query" or "header".
        ]
    ]
]

 

@OA\Info 작성한 곳에 추가

 * @OAS\SecurityScheme(
 *      securityScheme="bearer_token",
 *      type="http",
 *      scheme="bearer"
 * )

 

@OA\{Get | Post | Put | Delete} 안에 추가

 *     security={{"bearer_token":{}}},

- Beareer 쓰고 토큰 입력