OpenAPI를 사용하여 재사용 가능한 구성 요소 정의
APIGit
2023-06-15
OAS(OpenAPI 사양)는 API를 설명하는 강력하고 표준화된 방법을 제공합니다. 사양의 가장 중요한 기능 중 하나는components API 전체에서 다양한 요소를 재사용할 수 있어 일관성을 보장하고 중복성을 줄일 수 있습니다.
OAS의 구성 요소 이해
그만큼components 객체에는 스키마, 매개변수, 응답, 헤더, 요청 본문, 보안 체계 및 예제가 포함될 수 있습니다. 이 중앙 집중식 컨테이너는 API 정의 전반에 걸쳐 재사용성과 유지 관리성을 향상시킵니다.
일반적으로 재사용되는 구성 요소
스키마
스키마는 요청 및 응답 본문의 구조를 정의합니다. 이는 사용자 개체, 오류 메시지 구조 또는 기타 데이터 엔터티를 나타낼 수 있습니다.
예:
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
매개변수
매개변수는 경로의 ID 또는 페이지 매김에 대한 제한 및 오프셋과 같은 여러 작업에서 재사용할 수 있습니다.
예:
components:
parameters:
userId:
name: userId
in: path
required: true
schema:
type: integer
limitParam:
name: limit
in: query
schema:
type: integer
default: 10
응답
특히 오류 처리를 위한 공통 응답 구조는 한 번 정의하고 재사용하여 일관된 API 동작을 보장할 수 있습니다. 예:
components:
responses:
NotFound:
description: The specified resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
헤더
여러 엔드포인트에서 사용할 수 있는 표준 헤더는 한 번 정의하고 재사용할 수 있습니다.
예:
components:
headers:
X-Rate-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
보안 계획
공통 보안 체계를 정의하면 이를 API 전체에서 재사용할 수 있어 일관된 보안 관행을 보장할 수 있습니다.
예:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
재사용성을 위한 모범 사례
명명 규칙
구성요소에 대해 명확하고 설명이 포함된 이름을 사용하면 개발자가 구성요소를 더 쉽게 이해하고 재사용할 수 있습니다. 예를 들어 사용자 개체 스키마의 경우 User이고 일반적인 404 오류 응답의 경우 NotFound입니다.
조직과 구조
구성요소를 유형(예: 응답, 매개변수) 또는 도메인 영역(예: 인증, 사용자, 제품)별로 분류하여 논리적으로 구성합니다.
과도한 모듈화 방지
재사용성이 핵심이지만 너무 세분화하면 API 사양을 이해하고 유지 관리하는 것이 복잡해질 수 있습니다. 균형이 중요합니다.
예시 시나리오
일반적인 오류 응답 스키마
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
페이지 매김을 위한 쿼리 매개변수 재사용
paths:
/users:
get:
parameters:
- $ref: '#/components/parameters/limitParam'
- name: offset
in: query
schema:
type: integer
default: 0
공유 인증 헤더
paths:
/protected/resource:
get:
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
결론
효과적으로 사용하기components OAS의 개체는 API 사양의 일관성과 유지 관리성을 크게 향상시킬 수 있습니다. 모범 사례를 준수하고 APIGIT의 직관적인 API 편집기를 활용함으로써 개발자는 효율적이고 재사용 가능하며 잘 구성된 API 정의를 만들 수 있습니다.
