PHP에서 Swagger를 사용하여 API 문서를 생성하는 방법-PHP 튜토리얼-php.cn

PHP에서 Swagger를 사용하여 API 문서를 생성하는 방법

WBOY

풀어 주다： 2023-06-17 10:50:02

원래의

1333명이 탐색했습니다.

웹 애플리케이션의 지속적인 개발과 함께 API는 현대 웹 애플리케이션 개발의 표준 중 하나가 되었습니다. 그러나 API의 수와 복잡성이 증가함에 따라 이를 유지 관리하고 문서화하는 것이 점점 더 복잡해지고 있습니다. 이 문제를 해결하기 위해 Swagger가 탄생했습니다. API 문서를 생성하는 도구로, 개발자가 API를 더 쉽게 유지 관리하고 문서화할 수 있도록 하며 시각적 문서 및 기타 다양한 기능도 제공합니다. 이 기사에서는 PHP에서 Swagger를 사용하여 API 문서를 생성하는 방법에 대해 설명합니다.

먼저 Swagger를 설치해야 합니다. Swagger에는 다양한 버전과 구현이 있지만 여기서는 Swagger를 PHP 코드에 쉽게 통합할 수 있게 해주는 오픈 소스 PHP 라이브러리인 Swagger-php를 사용하겠습니다. Composer를 사용하여 프로젝트에 Swagger-php를 설치할 수 있습니다.

composer require zircote/swagger-php

로그인 후 복사

Swagger-php가 설치되면 API에 대한 Swagger 사양 작성을 시작할 수 있습니다. Swagger 사양은 엔드포인트 URL, 요청 및 응답 매개변수, 데이터 모델, 오류 코드를 포함하여 API의 모든 세부정보를 설명하는 JSON 또는 YAML 파일입니다. Swagger-php에서는 PHP 주석을 사용하여 사양을 작성할 수 있습니다. 간단한 예를 살펴보겠습니다.

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */

로그인 후 복사

이 예에서는 @OA 주석을 사용하여 Swagger 사양을 작성했습니다. @OA는 Info, Get, Response 및 Parameter와 같은 다양한 유형의 Swagger 요소를 정의하는 데 사용되는 Swagger-php 라이브러리의 네임스페이스입니다. @OAInfo 주석을 사용하여 제목, 버전 등 API의 기본 정보를 설명할 수 있습니다. @OAGet 주석에서는 /users 및 /users/{id}라는 두 개의 엔드포인트를 정의합니다. 요청 매개변수와 응답을 설명하고 성공 및 오류 응답 코드를 지정합니다. 이것은 단지 작은 예일 뿐이지만 다른 @OA 주석을 사용하여 더 복잡한 Swagger 사양을 작성할 수 있고 API의 인증 및 권한 부여를 설명할 수도 있습니다.

Swagger 사양을 작성한 후에는 Swagger-php를 사용하여 이를 시각적 문서로 변환할 수 있습니다. 이를 위해 Swagger 사양을 렌더링하기 위한 HTML, CSS 및 JavaScript 라이브러리인 Swagger-ui를 사용할 수 있습니다. Swagger-ui를 통합하기 위해 PHP에서 Swagger-ui-php 패키지를 사용할 수 있습니다. Composer를 사용하여 프로젝트에 Swagger-ui-php를 설치할 수 있습니다.

composer require swagger-api/swagger-ui

로그인 후 복사

Swagger-ui-php가 설치되면 Swagger-ui를 PHP 애플리케이션에 통합할 수 있습니다. Swagger-ui를 로드하기 위해 HTML 코드에 다음 줄을 추가할 수 있습니다:

<link rel="stylesheet" type="text/css" href="/vendor/swagger-api/swagger-ui/dist/swagger-ui.css">
<div id="swagger-ui"></div>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-bundle.js"></script>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.onload = function() {
    // 使用来自后端的Swagger JSON文件构造请求
    SwaggerUIBundle({
      url: "/api/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset // 用于额外的UI依赖
      ],
      layout: "StandaloneLayout"
    })
  }
</script>

로그인 후 복사

이 예에서는 Swagger-ui의 CSS 및 JavaScript 파일을 로드하고 "swagger-ui" ID가 포함된 파일로 렌더링합니다. DIV 요소. 우리는 JavaScript 코드를 사용하여 백엔드에서 Swagger JSON 파일을 로드하고 SwaggerUIBundle을 사용하여 이를 아름다운 문서로 변환합니다.

마지막으로 Swagger-ui가 Swagger 사양을 로드하려면 Swagger JSON 파일을 반환하는 경로를 애플리케이션에 추가해야 합니다.

use OpenApiAnnotations as OA;

$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

// 或者用这种方式

/**
 * @OAServer(url="http://localhost:8000")
 */

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */
$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

로그인 후 복사

이 예에서는 이전 예와 달리 OpenApi 주석을 사용하여 Swagger 사양을 작성합니다. 또한 Swagger JSON 파일을 반환하는 경로를 추가했습니다. OpenApiscan PHP 함수를 사용하여 경로 폴더를 스캔하고 API 정의를 Swagger JSON 객체로 변환한 다음 JSON 문자열로 변환하여 클라이언트에 반환합니다.

이 기사에서는 Swagger-php 및 Swagger-ui를 사용하여 PHP에서 API 문서를 생성하는 방법을 배웠습니다. API의 수와 복잡성이 증가함에 따라 Swagger는 시각적 API 문서 및 기타 다양한 기능을 제공하는 동시에 API를 보다 쉽게 유지 관리하고 문서화하는 데 도움이 될 수 있습니다. PHP 주석을 사용하여 Swagger 사양을 작성하면 수동으로 문서를 작성하는 것을 방지하고 코드를 더 명확하고 유지 관리하기 쉽게 만들 수 있습니다.

위 내용은 PHP에서 Swagger를 사용하여 API 문서를 생성하는 방법의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!