OpenAPI 3.1 명세서를 작성하는 과정은 구조적이고 체계적인 접근을 요구합니다. OpenAPI 3.1은 이전 버전들에 비해 몇 가지 향상된 기능과 JSON Schema의 최신 버전을 지원합니다. 다음은 OpenAPI 3.1 명세서를 작성하기 위한 기본 단계입니다.
1. 기본 구조 이해하기
OpenAPI 문서는 일반적으로 세 가지 주요 부분으로 구성됩니다:
openapi: 사용 중인 OpenAPI 명세의 버전을 나타냅니다.info: API에 대한 기본 정보를 제공합니다 (예: 제목, 버전, 설명).paths: 실제 API 엔드포인트와 해당 작업(메소드)을 정의합니다.
2. openapi 및 info 섹션 작성하기
문서의 시작 부분에는 명세서의 버전과 API에 대한 기본적인 정보를 포함해야 합니다.
openapi: 3.1.0
info:
title: Sample API
description: A sample API to illustrate OpenAPI concepts
version: 1.0.0
3. paths 섹션 정의하기
paths 섹션에서는 API가 제공하는 각 엔드포인트와 해당 HTTP 메소드를 정의합니다. 각 경로에는 하나 이상의 작업(예: get, post, put, delete)이 포함될 수 있습니다.
paths:
/items:
get:
summary: List all items
responses:
'200':
description: A list of items
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Item'
4. components 섹션으로 재사용 가능한 구성요소 정의하기
재사용 가능한 구성요소(예: 스키마, 응답, 파라미터, 보안 스키마)는 components 섹션에 정의됩니다. 이를 통해 문서 전반에 걸쳐 일관성을 유지하고 중복을 줄일 수 있습니다.
components:
schemas:
Item:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
5. 추가 세부 사항 추가하기
OpenAPI 명세는 매우 유연하며, 보안 요구사항, 태그, 외부 문서 링크 등과 같은 추가적인 정보를 포함할 수 있습니다.
6. 문서 검증 및 테스트
작성한 명세서를 검증하고 테스트하기 위해 Swagger Editor나 Redocly와 같은 도구를 사용할 수 있습니다. 이 단계는 문법 오류를 수정하고, 명세서가 의도한 대로 작동하는지 확인하는 데 중요합니다.
도구 사용하기
명세서를 수동으로 작성하는 것 외에도, SwaggerHub, Stoplight Studio와 같은 도구를 사용하여 OpenAPI 명세서를 더 쉽게 작성하고 관리할 수 있습니다. 이러한 도구들은 자동 완성, 문법 검사, 시각적 편집기를 제공하여 명세서 작성 과정을 간소화합니다.
OpenAPI 3.1 명세서 작성은 복잡할 수 있으나, 이러한 기본 단계와 도구들을 사용하면 과정을 보다 쉽게 진행할 수 있습니다.