openapi 란

OpenAPI는 **RESTful API(애플리케이션 프로그래밍 인터페이스)**를 설계, 생성, 문서화, 유지 관리하는 데 사용되는 표준 명세(specification)입니다. 간단히 말해, API를 사람들이 이해하고 시스템이 실행할 수 있도록 체계적으로 문서화하는 방법이라고 볼 수 있습니다.

OpenAPI의 핵심 개념

1. API의 설계와 문서화를 표준화: OpenAPI 명세는 API의 구조, 동작, 데이터 형식을 자세히 정의합니다. 이를 통해 개발자나 사용자가 API를 쉽게 이해하고 사용할 수 있습니다.
2. JSON 또는 YAML 형식으로 작성: OpenAPI는 사람이 읽기 쉬운 형식인 JSON 또는 YAML 파일로 API의 동작을 명확히 기술합니다.
3. 도구와의 호환성: OpenAPI는 Swagger와 같은 도구와 연동하여 문서화, 테스트, 코드 생성 등을 자동화할 수 있도록 돕습니다.

---

OpenAPI로 무엇을 할 수 있나요?

• API 설계: 명세를 먼저 작성한 뒤, 그에 따라 API를 구현하거나 수정할 수 있습니다. 이를 **"설계 우선 접근법"**이라 부릅니다.
• API 문서화: 작성된 명세를 기반으로 자동으로 보기 쉬운 인터페이스 문서를 생성할 수 있습니다.
• 자동 코드 생성: 서버 및 클라이언트 코드의 뼈대를 자동으로 생성해 개발 생산성을 높일 수 있습니다.
• API 테스트: API 동작을 테스트하고, 품질을 유지할 수 있습니다.

---

OpenAPI 명세 파일의 주요 구성 요소

• info: API 이름, 버전, 설명과 같은 기본 정보.
• paths: API의 엔드포인트(예: /users, /products)와 각 경로에서 지원하는 작업(GET, POST, PUT, DELETE 등).
• components: 공통적으로 재사용할 수 있는 데이터 모델, 보안 스키마 등.
• security: 인증 및 권한 부여 방법 정의(OAuth, API 키 등).
• servers: API가 배포될 서버 URL 정보.

---

OpenAPI의 장점

1. 표준화된 문서: 누구나 이해하기 쉬운 API 문서를 생성.
2. 자동화 지원: 다양한 개발 툴과 통합해 빠르고 효율적인 개발 가능.
3. 협업 강화: 명확한 명세를 공유해 개발자와 이해관계자 간의 협업을 용이하게 함.
4. 재사용 가능성: 공통 모델과 컴포넌트를 재사용해 유지보수를 간소화.

---

예시

다음은 간단한 OpenAPI 명세 예제입니다 (YAML 형식):

openapi: 3.0.0
info:
  title: 간단한 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 사용자 목록 조회
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

위 명세는 /users 경로에서 GET 요청을 보내면 사용자 목록(문자열 배열)을 반환하는 API를 정의한 것입니다.

---

요약

• OpenAPI는 API 설계와 문서화를 표준화한 시스템.
• YAML/JSON 형식으로 API의 모든 내용을 명확히 정의.
• Swagger와 같은 도구와 결합해 강력한 문서화와 코드 생성 기능 제공.
• 표준을 통해 API 설계 및 개발 과정을 단순화하고 효율화함.