[Laravel] Laravel 프로젝트에 Swagger 적용

    본 게시글은 Laravel에서 사용하는 아키텍처 방식인 RESTful API를 문서화하고 자동화 테스트를 하기 위한 글이다. 

  도입 배경은 RESTful 아키텍처로 운영하게 되면 API에 대한 문서가 필요한데 SpreadSheet 형태로 작성하여 관리하면 즉각 적용하기도 어렵고 API 테스트를 위해 POSTMAN과 같은 플랫폼을 이용하면 테스트를 진행하면 모든 테스트 케이스를 작성하고 실행해야 하는 단점이 존재한다. 

  위와 같은 단점을 보완하여 RESTful API 문서를 즉각적으로 반영하고 빠르게 테스트를 진행하기 위해 보편적으로 사용되는 swagger 프레임 워크를 이용한다. 

용어정리

 

Open API  
: 단어 그대로 “개방된 API”를 의미함. 즉, 누구나 사용할 수 있도록 API의 Endpoint가 개방되어있다면 Open API를 뜻한다.  예시로 기상청의 단기예보 조회 API, 우체국의 우편번호 API 등이 있으며, Public API라고도 함.

 

OpenAPI
: OpenAPI는 OpenAPI Specification(OAS)라고도 부르는데, 이는 RESTful API를 기 정의((Specification))된 규칙에 맞게 API Spec을 json이나 yaml로 표현하는 방식을 의미함. 직접 소스코드나 문서를 보지 않고 서비스를 이해할 수 있다는 장점이 있다.

OpenAPI Specification(OAS) 2.0 / 3.0

: 2015년 Swagger Specification을 OpenAPI Initiative에 기부하면서 OpenAPI Specification(OAS)로 명칭이 바뀌었고, 그 이후 첫번째 major release가 OAS3.0 이다. 2.0 때보다 구조가 더 단순해졌고, 재사용성이 증가될 수 있도록 개발되었다.

 

Swagger

: REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트이다.

 

Annotation

: 사전적 의미로는 주석이라는 뜻이다. PHP에서 Annotation은 코드 사이에 주석처럼 쓰이며 특별한 의미, 기능을 수행하도록 하는 기술이다. 프로그램에게 추가적인 정보를 제공해주는 메타데이터라고 볼 수 있다.

 

Framework 및 Library 검토

 

1. Framework
   RESTful API문서를 자동화하는 도구로 대표적으로 Spring REST Docs와 Swagger가 있다. 본 프로젝트에서는 Laravel에 적용하여 사용할 예정이므로 Swagger를 이용하도록 한다.

 Swagger에서 사용할 수 있는 도구는 아래와 같다.

• Swagger Editor : 브라우저 기반의 편집기, OpenAPI Spec을 쉽게 작성할 수 있게 도와줌
• Swagger Codegen : OpenAPI spec문서를 브라우저에서 확인할 수 있게 해줌, API Test도 가능
• Swagger UI : OpenAPI spec에 맞게 Server나 Client의 stub code생성

2. Library
  Laravel에서 사용할 수 있는 Swagger Library는 zircote와 L5-Swagger가 있다. 각 특징은 아래와 같다.

• zircote : Laravel 내에서 작성한 Annotation을 이용하여 RESTful에 대한 OpenAPI 문서(json, yaml)를 생성한다.
• L5-Swagger : zircote와 동일하게 OpenAPI문서(json, yaml)를 생성할 뿐만 아니라 이미 생성된 문서를 import할 수 있고, 프로젝트내 생성된 문서를 Laravel과 동일한 환경에서 Swagger-ui를 실행함.

본 프로젝트에서는 위의 특징을 고려하여 L5-Swagger를 선정하여 사용하도록 한다.

 

설치 및 구성

 

  본 글에서는 L5-Swagger 라이브러리를 이용한다. zircote 라이브러리 설치 및 예제는 아래 링크를 참고한다.

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

 

[Laravel] Swagger API 적용 하기

 

L5-Swagger를 설치하기 앞서 zircote도 동일하게 php artisan 혹은 composer 를 이용하여 설치한다. Laravel 9.x버전 기준으로 php 8.1 이상이 요구되므로 로컬내 설치된 php 버전을 맞게 업데이트하도록 한다.

 

설치 및 구성 과정은 공식 Github와 블로그 글을 참고하였다.

 

GitHub - DarkaOnLine/L5-Swagger: OpenApi or Swagger integration to Laravel

[Laravel] Laravel에서 Swagger 사용하기!

공식 Github의 wiki를 참고하면 Laravel 버전별 설치 커멘드가 있다. 본 글에서는 Laravel 9.x 버전을 기준으로 한다.

1.설치 (패키지 추가/제거)

$ composer require "darkaonline/l5-swagger" # 패키지 추가
$ composer remove "darkaonline/l5-swagger" # 패키지 제거

2. view 파일 및 config 파일 생성

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

• config 파일: swagger 관련 환경 설정 (project/config/l5-swagger.php)
• view 파일: swagger-ui 관리 (project/resources/views/vendor/l5-swagger)

 

3. config 파일 구성

 

가. page title 수정

: 아래 항목을 검색하여 'title'항목 수정 (Line 8)

'api' => [
                'title' => 'L5 Swagger UI',
            ],

나. 라우팅 정보 수정 (접근 URL)

: 아래 항목을 검색하여 'api' 항목 수정 (Line 15)

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

 

 

다. 적용 파일명 변경

: 아래 항목에서 ‘docs_json', 'docs_yaml’ 항목을 수정한다. (Line 26, 31)

'paths' => [
                /*
                 * File name of the generated json documentation file
                */
                'docs_json' => 'api-docs.json',

                /*
                 * File name of the generated YAML documentation file
                */
                'docs_yaml' => 'api-docs.yaml',

 

라. openapi문서 import 경로

: 기본경로(project/public/docs)

‘routes' → 'docs’ 항목을 수정한다. (Line 53)

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

마. openapi 문서 생성 경로

: 기본경로(project/storage/api-docs)

‘paths' → 'docs’ 항목을 수정한다. (Line 80)

       'paths' => [
            /*
             * Absolute path to location where parsed annotations will be stored
            */
            'docs' => storage_path('api-docs'),

4. service provider 등록
: project/config/app.php에서 providers 배열에 L5Swagger\L5SwaggerServiceProvider::class, 추가

Annotation 적용

 

  Swagger 가 OpenAPI 문서로 자동으로 작성되도록 하려면 Laravel 내 Controller 등 API 작성 메소드 위에 Annotation으로 기술한다.

 

자세한 Annotation 메소드 및 파라미터 정보는 아래 링크를 참고한다.

Annotations | Swagger-PHP

 

@OA\info

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

 

Laravel Project 내 반드시 1개의 info Annotation이 존재해야 함.

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

 /** 
 * @OA\get(
 *     path="/api/user/{group}",
 *     tags={"회원"},
 *     summary="회원정보 조회",
 *     description="회원 정보를 조회함",
 *      @OA\Parameter(
 *          name="group",
 *          description="그룹",
 *          in="path",
 *          required=true,
 *          example="korean",
 *          @OA\Schema(type="string")
 *     ),
 *     @OA\Response(response="200", description="An example resource")
 * )
 **/

 

• {Get | Post | Put | Delete} Method 정보를 기입한다.
• Parameter
  • path: URL 경로
  • tags: Tag 정보
  • summary: 요약정보
  • description: 설명
  • @OA\Parameter : Mehod의 Parameter 정보를 기입한다.
  • @OA\RequestBody : Mehod의 RequestBody 정보를 기입한다.
  • @OA\Response : Mehod의 Response 정보를 기입한다.
  • operationRef:
  • operationId:
  • security: 

 

@OA\Parameter

/**
* @OA\Parameter(
*     name="group",
*     description="그룹명",
*     in="path",
*     required=true,
*     example="korean",
*     @OA\Schema(type="sting")
* )
**/

• {Get, Post, Put, Delete Method}의 Parameter를 기입한다.
• Parameter
  • name: Parameter 이름을 기입한다.
  • description: Parameter 설명을 기입한다.
  • in: Parameter의 위치를 기입한다.( path | header | cookie | query)
  • required: 필수 입력 유무를 설정한다. ( true | false )
  • example: 예시 값(Default)을 입력한다.
  • @OA\Schema: 입력 및 출력 데이터 유형 정의 (string, int ……)

 

@OA\RequestBody

/**
* @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")
*         )
*     )
* )
**/

• RequestBody 정보를 기입한다.

 

@OA\Response

/**
*     @OA\Response(response="200", description="An example resource")
**/

• API 응답 데이터를 기입한다.
• Parameter
  • response: response code를 기입한다.
  • description: response 설명 및 결과(head, body)

@OA\Schema(type="string")

• 입력 및 출력 데이터 유형의 정의.

@OA\Property
@OA\Items
@OA\JsonContent

 

API 문서 생성 및 테스트

 

  문서 내 Annotation을 작성 완료하였다면 정해진 경로에 OpeanAPI(json, yaml) 문서를 생성한다. 

$ php artisan l5-swagger:generate

Route에 입력한 URL 정보를 웹브라우저에 입력하여 접속한다.

http://”Laravel 접속 URL”/api/documentation

 접속 후 아래와 같은 페이지를 볼 수 있다. 기존에 입력한 Example 데이터로 테스트를 진행할 수 있고 사용자가 임의로 입력하여 테스트를 진행할 수 있다. 

Project Design 

 

  디자인 설계는 아래 링크 예시를 참고한다.

Swagger UI

 

 

활용방안

  Open API를 제공하는 서비스라면 Swagger가 일반 사용자에게 공개되어도 무방하다고 판단되지만 SaaS 서비스에서는 외부로 공개되는 것이 적절하지 않다고 판단됨.

 

따라서  테스트 및 개발 버전에서는 Swagger를 포함하여 빌드하고, 릴리즈 버전에서는 제외하고 배포 하는 것이 적절하다고 판단됨.

테스트 및 개발 버전에서 제거되어야 하는 항목은 아래와 같음.

• l5-swagger Package
• view(vendor/darkaonline/l5-swagger/resources/views), config(resources/views/vendor/l5-swagger) File
• 생성된 OpenAPI(json, yaml) File 

 

 

참고사이트

 

• https://gruuuuu.github.io/programming/openapi/
• https://gruuuuu.github.io/programming/openapi/
• https://editor.swagger.io/#!/
• https://ivankolodiy.medium.com/how-to-write-swagger-documentation-for-laravel-api-tips-examples-5510fb392a94

 

 

 

 

※ 본 게시글의 정보가 잘못 되었거나 부족한 부분에 대한 피드백을 환영합니다.

 

 

* CopyRight 2023. Jay Park All rights reserved.