OpenAPI 3.0의 주요 변경점 및 기능 개선 사항

OpenAPI 3.0은 RESTful API 설계 및 문서화 방식을 혁신적으로 개선한 표준 사양입니다. 2017년 출시 이후 기존 Swagger 2.0 대비 구조적 개편과 새로운 기능 추가를 통해 현대적 API 개발 요구사항을 충족시키고 있습니다. 본 장에서는 OpenAPI 3.0의 핵심 변경 사항을 체계적으로 분석합니다.

1. 구조적 개편 및 재사용성 강화

1.1 서버 정의 방식 개선

복수 환경 지원: servers 객체를 도입해 단일 API에 대한 개발/테스트/운영 서버 URL을 동시 정의 가능

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://sandbox.example.com/v1
    description: Sandbox server

기존 방식 폐지: Swagger 2.0의 host, basePath, schemes 필드를 통합

1.2 컴포넌트 시스템 도입

재사용 리소스 관리: components 섹션에서 스키마, 매개변수, 응답 등을 전역 정의

components:
  schemas:
    User:
      type: object
      properties:
        id: {type: integer}
        name: {type: string}
  parameters:
    userIdParam:
      in: path
      name: id
      schema: {type: integer}

참조 메커니즘: $ref를 이용한 컴포넌트 재사용으로 문서 중복 최소화

2. 데이터 모델링 및 스키마 기능 강화

2.1 JSON Schema 확장 지원

조합 스키마: oneOf, anyOf, not 키워드 추가로 복잡 데이터 구조 표현 가능

schemas:
  Pet:
    oneOf:
      - $ref: '#/components/schemas/Cat'
      - $ref: '#/components/schemas/Dog'

데이터 타입 세분화: format 속성에 int32, date-time, password 등 추가

2.2 예제 관리 체계 개선

다중 예제 지원: 단일 필드에 여러 예시값 표기 가능

parameters:
  - name: status
    in: query
    schema:
      type: string
      enum: [active, pending, closed]
    examples:
      normalCase: {value: 'active'}
      edgeCase: {value: 'pending'}

3. 요청/응답 처리 방식 진화

3.1 요청 본문 처리

requestBody 도입: 기존 body 파라미터 대체 및 미디어 타입별 스키마 정의 지원

post:
  requestBody:
    content:
      application/json:
        schema: { $ref: '#/components/schemas/User' }
      application/xml:
        schema: { $ref: '#/components/schemas/User' }

3.2 응답 처리 개선

미디어 타입 기반 응답: content 객체를 통해 형식별 응답 구조 정의

responses:
  '200':
    content:
      application/json:
        schema: { $ref: '#/components/schemas/User' }
      text/csv:
        schema: { type: string }

4. 비동기 API 지원 기능 추가

4.1 콜백 기능

웹훅 지원: 비동기 작업 완료 시 외부 시스템 통지 메커니즘 구현

callbacks:
  subscriptionEvent:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Event' }

4.2 링크 기능

작업 간 관계 정의: 응답 값 기반 후속 작업 자동화

links:
  GetUserByOrder:
    operationId: getUser
    parameters:
      userId: '$response.body#/userId'

5. 보안 체계 개선

5.1 인증 방식 확장

쿠키 기반 인증: securitySchemes에 cookieAuth 타입 추가

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: SESSIONID

5.2 OAuth 2.0 강화

OpenID Connect 지원: openIdConnectUrl을 통한 자동 발견 메커니즘

securitySchemes:
  oAuth2:
    type: openIdConnect
    openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'

6. 문서화 및 테스트 기능 강화

6.1 상호작용 문서 생성

Swagger UI 통합: 실시간 API 테스트 가능한 대시보드 제공

const swaggerUi = require('swagger-ui-express');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

6.2 코드 생성기 개선

다중 언어 지원: OpenAPI Generator로 50+ 언어용 SDK 자동 생성
```
openapi-generator generate -i api.yaml -g java -o /output
```

결론: OpenAPI 3.0의 진화적 의미

OpenAPI 3.0은 단순한 버전 업그레이드를 넘어 REST API 설계 패러다임의 전환을 주도했습니다. 구조적 개편을 통해 재사용성과 확장성을 극대화했으며, 비동기 통신과 현대적 보안 요구사항을 반영한 점이 특징입니다. 특히 컴포넌트 기반 아키텍처와 JSON Schema의 심화 통합은 API First 개발 방법론의 실현을 가능하게 했습니다.

이러한 개선사항들은 단순한 기술적 진보를 넘어, API 생태계 전체의 협업 효율성과 품질 관리 체계를 근본적으로 변화시키고 있습니다. 개발팀은 OpenAPI 3.0 채택을 통해 설계-개발-테스트-문서화의 통합 워크플로우 구축이 가능해지며, 이는 디지털 트랜스포메이션 시대의 핵심 인프라 구축에 필수적인 요소로 자리매김하고 있습니다.

https://apidog.com/kr/blog/openapi-3-specification-tutorial-3/
https://apidog.com/kr/blog/openapi-specification-4/
https://www.ibm.com/docs/ko/SSEQTP_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/rwlp_api_openapi_interfaces.html?view=kc
https://soobindeveloper8.tistory.com/990
https://swagger.io/docs/specification/v3_0/components/
https://swagger.io/docs/specification/v3_0/describing-request-body/describing-request-body/
https://remainsoftware.com/docs/openapi/help/topic/com.remainsoftware.oas3.help/manuals/html/OpenAPI_Editor/OpenAPI_EditorCallbacks/OpenAPI_EditorCallbacks.html
https://swagger.io/docs/specification/v3_0/links/
https://blog.stoplight.io/difference-between-open-v2-v3-v31
https://community.meraki.com/t5/Developers-APIs/OpenAPI-v3-Officially-Supported/m-p/197649
https://blog.bitsrc.io/whats-new-in-openapi-3-0-f6604799782?gi=e6ed1a29b930
https://gruuuuu.github.io/programming/openapi/
https://wonsjung.tistory.com/584
https://swagger.io/specification/
https://www.baeldung.com/java-openapi2-openapi3-upgrade
https://tech.kakaopay.com/post/openapi-documentation/
https://openapispec.com/docs/what/what-are-the-differences-between-openapi-2-0-and-3-0/
https://jeonyoungho.github.io/posts/Open-API-3.0-Swagger-v3-%EC%83%81%EC%84%B8%EC%84%A4%EC%A0%95/
https://velog.io/@mj3242/Swagger-3.x-%EC%96%B4%EB%85%B8%ED%85%8C%EC%9D%B4%EC%85%98-%EC%A0%95%EB%A6%AC
https://help.salesforce.com/s/articleView?id=sf.external_services_examples_openapi_3_0.htm&language=ko&type=5
https://velog.io/@hyex/Swagger-Components-Section-OpenAPI3
https://spec.openapis.org/oas/v3.1.0.html
https://support.smartbear.com/swaggerhub/docs/en/domains/openapi-components.html
https://a.ml/docs/related-docs/openapi_3_components
https://eazyapi-1.gitbook.io/docs/open-api-guide/describing-request-body
https://swagger.io/resources/webinars/convert-api-to-oas-3-with-swagger-tools/
https://nordicapis.com/comparing-the-features-of-openapi-v3-vs-openapi-v2/
https://readme.com/resources/an-example-filled-guide-to-swagger-3-2
https://www.javacodegeeks.com/openapi-2-to-openapi-3-upgrafe-in-java.html
https://blog.bitsrc.io/whats-new-in-openapi-3-0-f6604799782

tobony? 또 보니?

Search This Blog