PHP 개발: Swagger를 사용하여 API 문서를 유지하는 방법-PHP 튜토리얼-php.cn

PHP 개발: Swagger를 사용하여 API 문서를 유지하는 방법

WBOY

풀어 주다： 2023-06-15 09:38:01

원래의

1014명이 탐색했습니다.

인터넷의 급속한 발전과 함께 Web API는 개방형 애플리케이션을 지원하는 핵심이 되었습니다. API의 확장성과 재사용성은 API를 다양한 시스템 간의 데이터 교환 및 협업을 위한 중요한 도구로 만듭니다. 그러나 개발자는 종종 API 문서를 유지 관리하고 API 안정성을 보장하는 방법이라는 일반적인 질문에 직면합니다.

Swagger는 API 설계, 문서화, 테스트 및 배포를 위한 완벽한 솔루션을 제공하는 오픈 소스 프레임워크입니다. 이 기사에서는 Swagger를 사용하여 기존 API를 더 잘 관리하고 유지하기 위해 API 문서를 유지하는 방법을 살펴봅니다.

1. Swagger의 기본 개념

Swagger는 API를 설명하는 JSON 또는 YAML 사양 파일을 통해 API를 생성하고 문서화합니다. 이 파일을 Swagger 사양이라고 합니다.

Swagger 사양 파일에는 다음 개념이 포함되어 있습니다.

Path: API 경로는 리소스의 식별자입니다. 예를 들어 /users는 모든 사용자를 나타내고 /users/{id}는 사용자를 나타냅니다.
메서드: GET, PUT, POST, DELETE 및 HEAD와 같은 HTTP 메서드입니다.
매개변수: 요청 매개변수(HTTP 요청 본문, URL 경로 및/또는 쿼리 문자열 매개변수).
응답: HTTP 응답 구조, 상태 코드 및 응답 본문(HTTP 응답 본문) 유형.
모델: 데이터 전송 개체(DTO) 및 응답 개체의 구조.
태그: 쉽게 읽을 수 있도록 API 리소스를 논리적으로 그룹화합니다.

2. Swagger 사용

Swagger UI 설치

Swagger UI는 Swagger 사양 파일을 대화형 인터페이스에 표시할 수 있는 오픈 소스 도구입니다. 주요 목적은 명확하고 대화형 문서를 제공하고 API를 테스트하고 디버그할 수 있도록 하는 것입니다.

다음 명령을 사용하여 Swagger UI를 설치합니다.

npm install swagger-ui-dist

로그인 후 복사

Write Swagger 사양 파일

Swagger 사양 파일을 작성하여 API의 경로, 메서드, 매개 변수, 응답 및 기타 정보를 설명합니다.

예는 다음과 같습니다.

swagger: '2.0'
info:
  title: User API Root
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      description: Returns all users
      produces:
        - application/json
      responses:
        200:
          description: A list of user names
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 123
              name:
                type: string
                example: John Doe

로그인 후 복사

이 예에서는 API 경로 "/users"와 응답으로 "id" 및 "name"이 포함된 JSON 개체 배열을 반환하는 GET 메서드를 정의합니다.

Swagger UI 통합

Swagger 사양 파일을 표시하려면 웹 애플리케이션에 Swagger UI를 통합하세요. 웹 페이지에 다음 HTML 코드를 추가합니다.

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "https://api.example.com/swagger",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
    }
  </script>
</body>
</html>

로그인 후 복사

이 예에서는 HTML 파일에 Swagger UI를 로드하고 Swagger 사양 파일의 URL 주소를 SwaggerUIBundle에 전달하여 API 문서를 렌더링합니다.

API 테스트 및 디버깅

Swagger UI를 사용하여 웹 애플리케이션에서 API를 테스트하고 디버그하세요.

Swagger UI를 통해 다음을 수행할 수 있습니다.

인터페이스 문서를 봅니다.
테스트를 자동화하고 API 응답 결과를 확인하세요.
코드 조각을 생성하는 동안 디버그 API.

요약

Swagger는 개발자에게 API 설계, 문서화, 테스트 및 배포를 위한 완벽한 솔루션을 제공할 수 있는 탁월한 프레임워크입니다. Swagger를 사용하면 기존 API를 더 잘 관리하고 유지할 수 있습니다. 이는 중앙 집중식 개발 모델에서 가장 좋은 방법 중 하나이기도 합니다.

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