Swagger(OpenAPI 3.0) 명세 250417

q1: Swagger(OpenAPI 3.0) 명세

a1:

Swagger(OpenAPI 3.0) 명세는 REST API의 구조와 동작을 명확하게 문서화하고 공유하기 위한 표준 포맷입니다.

개발자와 시스템 간의 연동을 더 쉽게 만들고, API 테스트 및 코드 자동 생성을 가능하게 해주는 매우 중요한 도구입니다.

⸻

1. 정의 요약

공식 명칭: OpenAPI Specification (버전 3.0 이상)
구 명칭: Swagger (이전 명칭이 Swagger였으나, 현재는 OpenAPI가 공식 명칭입니다)
형식: YAML 또는 JSON
목적: API 명세 작성, 자동 문서화, 테스트, SDK 생성 등
주요 도구: Swagger Editor, Swagger UI, Swagger Codegen, Postman 등

⸻

2. 어떤 내용을 담고 있나요?

예: 고객 대출 계약 개수 조회 API

paths:
  /loan/count:
    post:
      summary: 고객별 대출계약 개수 조회
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
      responses:
        '200':
          description: 계약 수 조회 성공

주요 구성요소

info: API 이름, 버전, 설명
servers: 호출 대상 서버 URL
paths: API 경로 및 메서드 (GET, POST 등)
components: 보안, 스키마, 공통 객체 정의
security: 인증 방식 (OAuth2, API Key 등)
requestBody/responses: 요청/응답 포맷 정의


⸻

3. 왜 중요한가요?

개발 속도 향상: API 명세만 보고도 프론트/백엔드 개발 동시 진행 가능
자동 문서화: Swagger UI 등으로 명세서를 웹페이지로 제공 가능
테스트 도구로 사용: Swagger Editor에서 실제 API 요청 가능
SDK 자동 생성: Swagger Codegen을 이용해 클라이언트 코드 자동 생성 가능
표준화: 다양한 시스템/업체 간 연동 시 동일한 포맷으로 소통 가능

⸻

4. 실제 사용 예시 도구
• Swagger Editor: 웹에서 직접 OpenAPI 명세 작성 및 테스트 가능
• Swagger UI: 문서화된 API를 웹 인터페이스로 제공
• Redoc: 고급 UI 기반 문서화 툴
• Postman: OpenAPI 불러와서 테스트 및 시나리오 구성 가능