Swagger-PHP는 PHP 프로젝트에 대한 Swagger 사양을 생성할 때 항상 떠오르는 첫 번째 도구입니다. 그럼 Swagger-PHP란 무엇일까요? Swagger-PHP를 사용하여 사양을 어떻게 생성할까요? 이 기사에서는 이러한 질문에 답하고 세부 정보를 소개하겠습니다.

Swagger-PHP란 무엇인가요

Swagger-PHP는 PHP에서 Swagger(현재 OpenAPI Specification으로 알려짐)를 사용하여 API 문서를 생성하는 도구입니다. Swagger-PHP는 PHP 개발자가 Swagger(OpenAPI) 사양에 기반한 API 문서를 작성하는 데 도움을 줍니다. 이 도구는 PHP 코드에서 Swagger(OpenAPI) 사양을 생성할 수 있습니다. 개발자는 코드에서 API 엔드포인트, 요청 및 응답을 정의하고 Swagger(OpenAPI) 사양을 자동으로 생성할 수 있습니다.

Swagger-PHP의 특징

Swagger-PHP는 OpenAPI 버전 3.0 및 3.1에 대한 사양 생성을 위해 사용되는 강력한 도구입니다. 또한 PHP 소스 코드를 사용하여 API를 기록할 수 있습니다. Swagger-PHP에서 사용되는 주석 속성은 문서 블록 또는 PHP 8.1일 수 있어 매우 유연하고 다재다능합니다.

문서 블록 또는 최신 PHP 버전으로 작업하든 관계없이 Swagger-PHP는 API 개발 프로세스를 간소화하고 전반적으로 더 효율적으로 만드는 데 도움이 됩니다.

Swagger-PHP 설치 및 설정 방법

Swagger-PHP를 사용하려면 먼저 설치해야 합니다. Swagger-PHP는 PHP의 종속성 관리자인 Composer를 사용하여 설치할 수 있습니다.

Swagger-PHP를 설치하려면 터미널에서 다음 명령어를 실행하세요:

composer require zircote/swagger-php

설치가 완료되면 Swagger-PHP를 사용하여 API에 대한 Swagger 문서를 생성할 수 있습니다.

다음으로, Swagger 인스턴스를 새로 생성하고 API 정보로 구성하여 Swagger-PHP를 설정해야 합니다. Swagger-PHP를 설정하는 방법의 예는 다음과 같습니다:

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="내 API",
 *         description="내 API에 대한 API 문서",
 *         @SWG\Contact(name="내 회사"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

이 예에서는 새로운 Swagger 인스턴스를 생성하고 기본 경로, 스킴, API 정보(버전, 제목, 설명, 연락처 및 라이센스)로 구성했습니다.

Swagger-PHP를 설정한 후에는 API 코드에 Swagger 주석을 추가하여 Swagger 문서를 생성할 수 있습니다. 다음 섹션에서 이에 대해 더 자세히 다룰 것입니다.

Swagger-PHP로 Swagger 문서 만들기

Swagger-PHP는 Swagger 문서를 생성하기 위한 PHP 라이브러리입니다. 이 섹션에서는 Swagger-PHP를 사용하여 Swagger 문서를 만드는 방법을 배웁니다.

1단계. API 정보 정의하기

먼저 API의 정보를 정의해야 합니다. 여기에는 API의 제목, 설명, 버전 등이 포함됩니다. 다음은 예시입니다:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => '내 API',
        'description' => '샘플 API 문서입니다.',
        'version' => '1.0.0'
    ]);

2단계. API 엔드포인트 정의하기

다음으로 API의 엔드포인트를 정의해야 합니다. 여기에는 각 엔드포인트에 대한 HTTP 메서드, 경로, 매개변수 및 응답이 포함됩니다. 다음은 예시입니다:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => '내 API',
        'description' => '샘플 API 문서입니다.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => '사용자 목록 가져오기.',
        'description' => '사용자 목록을 반환합니다.',
        'responses' => [
            '200' => [
                'description' => '사용자 목록.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => '새 사용자 생성.',
        'description' => '새 사용자를 생성합니다.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => '생성할 사용자입니다.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => '생성된 사용자.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ]);

3단계. 데이터 모델 정의하기

마지막으로 데이터 모델을 정의해야 합니다. 여기에는 각 모델의 속성 및 유형이 포함됩니다. 다음은 예시입니다:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => '내 API',
        'description' => '샘플 API 문서입니다.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => '사용자 목록 가져오기.',
        'description' => '사용자 목록을 반환합니다.',
        'responses' => [
            '200' => [
                'description' => '사용자 목록.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => '새 사용자 생성.',
        'description' => '새 사용자를 생성합니다.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => '생성할 사용자입니다.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => '생성된 사용자.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ])
    ->definitions([
        'User' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'name' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

4단계. Swagger 문서 내보내기

마지막으로 다음 코드를 사용하여 Swagger 문서를 출력할 수 있습니다:

header('Content-Type: application/json');
echo $swagger->toJson();

이 코드는 API 문서를 생성하는 데 사용할 수 있는 JSON 형식의 Swagger 문서를 출력합니다.

Swagger-PHP와 Swagger UI 통합하기

Swagger 문서의 이점을 충분히 활용하려면 문서를 보고 상호작용할 수 있는 사용자 친화적인 인터페이스가 중요합니다. 여기서 Swagger-UI가 필요합니다. Swagger-UI는 Swagger 문서를 분아하고 테스트하는 데 필요한 인터랙티브한 경험을 제공하는 웹 기반 인터페이스입니다.

Swagger-UI와 Swagger-PHP를 통합하는 과정은 간단합니다. 먼저 공식 GitHub 리포지토리에서 최신 버전의 Swagger-UI를 다운로드합니다. 그런 다음 다운로드한 압축 파일의 내용을 웹 서버의 디렉터리에 추출합니다.

다음으로 Swagger-UI의 진입점 역할을 할 새 PHP 파일을 생성합니다. 이 파일에서 Swagger-UI에 필요한 CSS 및 JavaScript 파일과 Swagger-UI JavaScript 라이브러리를 포함해야 합니다. 또한 API 문서가 포함된 Swagger-PHP에서 생성된 JSON 파일도 포함해야 합니다.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // 시스템 구축
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

위 예제에서 path/to 자리 표시자를 Swagger-UI CSS 및 JavaScript 파일과 Swagger-PHP에서 생성된 JSON 파일의 실제 경로로 변경하십시오.

이 파일을 생성한 후, 웹 브라우저에서 URL을 통해 Swagger-UI에 접근할 수 있습니다. API 문서를 표시하고 상호작용할 수 있는 완전히 기능하는 Swagger-UI 인터페이스를 볼 수 있어야 합니다.

결론적으로, Swagger-UI와 Swagger-PHP를 통합하는 과정은 간단하며 API 문서의 사용성을 크게 향상시킵니다. 위에서 설명한 단계를 따르면 개발자가 API를 이해하고 사용할 수 있도록 하는 사용자 친화적인 API 문서 인터페이스를 쉽게 만들 수 있습니다.

API 사양 공유하기

Swagger 사양을 생성한 후, 저는 종종 팀원들과 공유합니다. 이러한 경우, 우리는 종종 Swagger JSON 또는 OpenAPI yaml 형식으로 공유하지만, 이는 다소 구식처럼 보입니다.

여기서 Apidog은 Swagger JSON 또는 YAML 데이터에 기반하여 매우 읽기 쉬운 API 사양을 즉시 생성하는 완벽한 API 관리 도구입니다. 또한 이 API 사양을 API 공유 기능으로 쉽게 공유할 수 있습니다.

Apidog은 또한 API 생애 주기 관리 도구로서 다양한 기능을 제공합니다.

API 설계 및 사양 생성: Apidog은 코딩 없이 직관적으로 API를 설계할 수 있게 해주는 가장 쉬운 API 설계 도구로, OpenAPI 및 Swagger 사양을 편리하게 생성할 수 있습니다.

API 관리 및 단위 테스트: Apidog은 API를 효율적으로 관리하고 API 요청을 보내고 응답을 검증할 수 있어 단위 테스트를 아주 쉽게 만듭니다.

API 테스트 자동화: Apidog은 자동화된 테스트도 지원하며 CI/CD에 준비되어 있습니다. 이 기능을 사용하여 스레드 수 등을 설정하면 API 부하 테스트 및 API 테스트 자동화를 쉽게 구현할 수 있습니다.

결론

결론적으로, Swagger-PHP는 PHP 기반 API를 위한 Swagger 문서를 생성하는 강력한 도구입니다. 개발자는 API를 쉽게 문서화하고 다른 개발자가 접근할 수 있도록 할 수 있습니다. 또한 Swagger-UI와 Swagger-PHP를 통합하면 API 탐색 및 테스트를 위한 사용자 친화적인 인터페이스를 제공합니다.

Swagger-PHP에 대해 더 배우기 위한 리소스는 다음과 같습니다:

공식 문서: https://zircote.github.io/swagger-php/
GitHub 리포지토리: https://github.com/zircote/swagger-php
Swagger-UI: https://swagger.io/tools/swagger-ui/