[Laravel] Swagger API 적용 하기

1. zircote/swagger-php 설치

composer require zircote/swagger-php

//버전 지정
composer require zircote/swagger-php:3.3.2

- 삭제

composer remove zircote/swagger-php

 

 

2. Controller 등 API 작성 메소드 위에 애노테이션으로 기술하기

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */

 

-상세설명 (회원 등록 샘플)

/**
 * @OA\Post (
 *     path="/user",
 *     tags={"회원"},
 *     summary="회원 등록",
 *     description="회원 정보를 등록함",
 *     security={
 *         {"bearerAuth": {}}
 *     },
 *     operationId="UserController::userStore",
 *     @OA\Parameter(
 *          name="id",
 *          description="회원 번호",
 *          in="path",
 *          required=true,
 *          example="1",
 *          @OA\Schema(type="int")
 *     ),
 *     @OA\Parameter(
 *          name="name",
 *          description="회원 이름",
 *          in="path",
 *          required=true,
 *          example="홍길동",
 *          @OA\Schema(type="string")
 *     ),
 *     @OA\Parameter(
 *          name="phone",
 *          description="회원 전화번호",
 *          in="path",
 *          required=true,
 *          example="010-1234-1234",
 *          @OA\Schema(type="string")
 *     ),
 *     @OA\Response(
 *          response="200",
 *          description="성공",
 *          @OA\MediaType(
 *              mediaType="application/json",
 *              @OA\Schema(
 *                  allOf={
 *                      @OA\Schema(ref="#/components/schemas/UserController-userStore")
 *                  }
 *              )
 *          )
 *     ),
 *     @OA\Response(
 *          response="401",
 *          description="실패",
 *              @OA\MediaType(
 *                  mediaType="application/json",
 *                  @OA\Schema(
 *                      @OA\Property(property="result", type="string", description="결과코드", example="401"),
 *                      @OA\Property(property="message", type="string", description="메시지", example="조회오류"),
 *                  )
 *              )
 *     ),
 *     @OA\RequestBody(
 *         @OA\MediaType(
 *             mediaType="application/json",
 *             @OA\Schema(
 *                  @OA\Property(property="id", type="int", description="회원 번호", example=1),
 *                  @OA\Property(property="name", type="string", description="회원 이름", example="홍길동"),
 *                  @OA\Property(property="phone", type="string", description="회원 전화번호", example="010-1234-1234"),
 *             )
 *         )
 *     )
 * )
 *
 * @OA\Schema(
 *      schema="UserController-userStore",
 *          @OA\Property(property="result", type="string", description="결과코드", example="200"),
 *          @OA\Property(property="message", type="string", description="메시지", example="회원이 입력 되었습니다."),
 *          @OA\Property(property="userInfo", type="array",
 *              @OA\Property(property="id", type="int", description="회원 아이디", example=1),
 *              @OA\Property(property="name", type="string", description="회원 이름", example="홍길동"),
 *              @OA\Property(property="phone", type="string", description="회원 전화번호", example="010-1234-1234"),
 *          ),
 *      ),
 */

 

- 기본적으로 json 형태로 기술된다.

- array도 만들수는 있지만, 리스트 형태로는 작성되지 않는다. [1,2,3,4] 형태 x 

 

- 배열 사용 예

* @OA\Schema(
*      schema="UserController-userStore",
*          @OA\Property(property="result", type="string", description="결과코드", example="200"),
*          @OA\Property(property="message", type="string", description="메시지", example="회원이 입력 되었습니다."),
*          @OA\Property(property="userInfo", type="array",
*              @OA\Items(
*                  @OA\Property(property="1", type="int", description="회원 아이디", example=1),
*                  @OA\Property(property="2", type="string", description="회원 이름", example="홍길동"),
*                  @OA\Property(property="3", type="string", description="회원 전화번호", example="010-1234-1234"),
*              ),
*          ),
*      ),
*/

type="array" 로 작성하고, Items 로 기술한다.

 

- Schema 여러개 사용하기

*     @OA\Response(
*          response="200",
*          description="성공",
*          @OA\MediaType(
*              mediaType="application/json",
*              @OA\Schema(
*                  allOf={
*                      @OA\Schema(
*                          @OA\Property(property="result", type="string", description="결과코드", example="200"),
*                          @OA\Property(property="message", type="string", description="메시지", example="성공")
*                      ),
*                      @OA\Schema(ref="#/components/schemas/UserController-Info")
*                  }
*              )
*          )
*     ),

위 처럼 schema 에 property를 직접 기술 하고, 그 아래에 ref로 schema를 불러와서 같이 사용 가능

 

 

3. 기술한 내용들을 swagger api 문서로 생성하기

프로젝트 폴더로 이동하여 openapi 명령어로 실행

# ./vendor/bin/openapi -o swagger-ui/swagger.json --format json ./app

openapi 를 실행해서 json 포맷으로 ./app 폴더 내에 있는 모든 애노테이션들을 찾아서 자동으로 문서를 생성해줘라 라는 의미

 

- 결과

 

 

4. zircote/swagger-php

https://github.com/zircote/swagger-php

GitHub - zircote/swagger-php: A php swagger annotation and parsing library