PHP 개발: Swagger를 사용하여 API 문서를 유지하는 방법
- WBOY원래의
- 2023-06-15 09:37:17988검색
인터넷의 급속한 발전과 함께 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 중국어 웹사이트의 기타 관련 기사를 참조하세요!