OpenAPI 3.0 스펙 완전 정복

OpenAPI 3.0

 

오픈 API 스펙은 현대 웹 개발에서 API를 정의하고 문서화하는 데 필수적인 도구가 되었습니다.

특히 OpenAPI 3.0은 직관적이고 효율적인 API 디자인을 가능하게 해 줍니다.

 

OpenAPI 3.0이 개발 생태계에 어떤 영향을 미치는지, 그리고 실제 서비스에서 어떻게 활용할 수 있는지 심도 있게 다뤄보려 합니다.

1. OpenAPI란 무엇인가?

OpenAPI는 RESTful API의 명세를 작성하기 위한 언어 중 하나로, 이전의 Swagger 스펙을 기반으로 발전하였습니다.

API의 구조, 요청과 응답 형식, 인증 방법 등을 정의합니다.

이는 API 소비자와 생산자 간의 명확한 계약을 제공하여, 개발 효율성과 유지보수성을 높여줍니다.

1.1 주요 특징

• 언어 및 플랫폼 독립적: JSON 또는 YAML 형식으로 작성되어 다양한 환경에서 활용 가능
• 인간과 기계 모두가 읽기 쉬운 형식: 개발자와 자동화 도구 모두에게 유용확장성: 커스텀 확장을 통해 특정 요구사항 충족 가능
• 확장성: 커스텀 확장을 통해 특정 요구사항 충족 가능

1.2 OpenAPI 3.0의 주요 개선 사항

OpenAPI 3.0은 이전 버전인 Swagger 2.0에서 많은 부분이 개선되었습니다.

• Components: 재사용 가능한 스키마, 응답, 파라미터 등을 정의할 수 있어 코드의 중복을 줄입니다.
• Callback: 비동기 통신을 위한 콜백 메커니즘을 지원합니다.
• OneOf/AnyOf/AllOf: 복잡한 데이터 모델링이 가능해졌습니다.
• Multiple Servers: 하나의 스펙에서 여러 서버 환경(dev, staging, production)을 정의할 수 있습니다.
• Improved Security Definitions: 보안 스키마 정의가 더 유연해졌습니다.
• Content Type의 확장: 이제 requestBody를 통해 다양한 콘텐츠 타입을 지원할 수 있습니다. 예를 들어, JSON뿐만 아니라 XML이나 폼 데이터도 쉽게 정의할 수 있게 되었습니다.

2.  OpenAPI 3.0 스펙의 핵심 요소 심층 분석

2.1 메타정보

이 섹션에서는 API의 기본 정보를 정의합니다.

버전 관리에 특히 주의를 기울여야 합니다.

openapi: 3.0.0
info:
  title: 예제 API
  version: 1.0.0
  description: API에 대한 상세 설명

2.2 서버 정보

여러 환경에 대한 서버 정보를 명시할 수 있어, 개발 단계별로 다른 엔드포인트를 쉽게 관리할 수 있습니다.

servers:
  - url: https://api.example.com/v1
    description: 프로덕션 서버
  - url: https://staging-api.example.com/v1
    description: 스테이징 서버

2.3 경로 및 작업

각 API 엔드포인트와 해당 작업(GET, POST 등)을 정의합니다.

여기서 $ref를 사용해 재사용 가능한 컴포넌트를 참조할 수 있습니다.

paths:
  /users:
    get:
      summary: 사용자 목록 조회
      responses:
        '200':
          description: 성공적인 응답
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

2.4 컴포넌트

재사용 가능한 스키마, 보안 정의 등을 포함합니다.

이를 통해 문서의 일관성을 유지하고 중복을 줄일 수 있습니다.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

• schemas: 데이터 모델을 정의합니다.
• parameters: 공통으로 사용하는 파라미터를 정의합니다.
• responses: 공통 응답을 정의합니다.
• securitySchemes: 인증 방법을 정의합니다.

2.5 고급 스키마 정의

OpenAPI 3.0에서는 JSON Schema를 확장하여 복잡한 데이터 구조를 표현할 수 있습니다.

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

• oneOf: 여러 스키마 중 하나를 만족해야 함
• anyOf: 여러 스키마 중 하나 이상을 만족해야 함
• allOf: 여러 스키마를 모두 만족해야 함
• not: 특정 스키마를 제외

2.6 보안 스키마 정의

보안 스키마는 API의 인증 및 인가 방법을 정의합니다.

• API Key
• HTTP Authentication
• OAuth 2.0
• OpenID Connect Discovery

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

3. 실무에서의 OpenAPI 3.0 활용 방법

3.1 API 설계 및 문서화 프로세스

• API 스펙 작성: API의 구조와 동작을 먼저 정의합니다.
• 팀원들과 공유: 스펙을 기반으로 팀원들과 논의하여 개선합니다.
• 자동화 도구 활용: 스펙을 사용하여 서버 스텁, 클라이언트 SDK, 문서 등을 생성합니다.
• 테스트 및 검증: 스펙에 정의된 대로 API가 동작하는지 확인합니다.

3.2 프런트엔드 자동화와 코드 생성

OpenAPI 3.0은 프런트엔드 코드 자동 생성에도 활용할 수 있습니다.

예를 들어, TypeScript와 React Query를 사용하는 프로젝트라면 openapi-generator-cli를 사용해 API 클라이언트를 자동으로 생성할 수 있습니다.

이를 통해 프런트엔드 개발자는 수동으로 API 호출 함수를 작성하는 일을 줄이고, 타입 안전성을 강화할 수 있습니다.

npx @openapitools/openapi-generator-cli generate -i api-spec.yaml -g typescript-fetch -o ./generated-api

이렇게 생성된 코드들은 서버의 변경사항이 있을 때마다 명세서를 기반으로 갱신할 수 있어 유지보수 측면에서 큰 장점을 제공합니다.

특히 자동 생성된 코드가 API 호출을 캡슐화하여 사용자의 실수를 줄이고, 일관된 에러 처리 방식을 적용하는 데도 도움을 줍니다.

3.3 백엔드의 API 게이트웨이 관리

OpenAPI 3.0은 API Gateway와도 잘 연동됩니다.

예를 들어, AWS API Gateway에서는 OpenAPI 스펙 파일을 기반으로 엔드포인트를 설정하고 배포할 수 있습니다.

이를 통해 백엔드 팀은 클라이언트의 요청을 다양한 서비스로 라우팅 하거나 API 레이트 리밋(rate limit) 설정을 쉽게 관리할 수 있습니다.

x-amazon-apigateway-integration:
  type: aws_proxy
  uri: arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations
  httpMethod: POST

3.4 API 문서화

스펙을 기반으로 Swagger UI나 Redoc을 사용하여 읽기 쉽고 탐색하기 쉬운 API 문서를 생성할 수 있습니다.

이는 내부 팀원들뿐만 아니라 외부 개발자들에게도 유용합니다.

3.5 테스트 자동화

스펙을 활용하여 테스트 케이스를 자동 생성하고, API의 동작이 스펙과 일치하는지 검증할 수 있습니다.

• Dredd: 스펙과 실제 API의 일치 여부를 테스트합니다.
• Schemathesis: 다양한 입력 값을 사용하여 API의 견고성을 테스트합니다.

describe('API Contract Tests', () => {
  it('should match OpenAPI specification', async () => {
    const response = await request(app)
      .get('/api/users')
      .expect(200);
    
    expect(response.body).toMatchSchema(openApiSchema.components.schemas.UserList);
  });
});

3.6 CI/CD 파이프라인 통합

스펙 검증, 코드 생성, 테스트 실행 등을 CI/CD 파이프라인에 통합하여 개발 프로세스를 자동화하고 품질을 높일 수 있습니다.

4. 실제 서비스 적용 사례

4.1 마이크로서비스 간 통신

OpenAPI 3.0은 마이크로서비스 환경에서 큰 역할을 합니다.

각 마이크로서비스가 제공하는 API를 명확히 정의하고, 이를 통해 서비스 간의 의존성을 줄이면서도 안정적으로 통신할 수 있게 해 줍니다.

예를 들어, 주문 서비스와 결제 서비스가 분리된 환경에서, 결제 서비스는 주문 서비스의 OpenAPI 명세서를 참조하여 정확한 데이터 형식과 엔드포인트를 사용할 수 있습니다.

4.2 버저닝과 Backward Compatibility

API의 버저닝 관리에서도 OpenAPI 3.0은 효과적입니다.

예를 들어 /v1과 /v2 같은 경로를 통해 서로 다른 버전의 API를 유지할 때, 명세서를 각 버전별로 관리하여 클라이언트가 어떤 버전을 호출해야 하는지 명확하게 이해할 수 있게 합니다.

또한, deprecated 필드를 사용해 사용 중단 예정인 API에 대한 정보를 제공하여 클라이언트가 미리 대비할 수 있도록 돕습니다.

OpenAPI 3.0을 통한 개발 효율성 극대화

OpenAPI 3.0은 프런트엔드와 백엔드 모두에게 명확한 계약을 제공하여 개발 과정에서의 혼란을 줄이고, 자동화와 표준화를 통해 개발 효율성을 극대화합니다.

API 명세를 코드로 작성하고 이를 유지보수하는 일은 다소 번거로울 수 있지만, 장기적으로는 유지보수 비용을 줄이고 개발자 간의 협업을 원활하게 해주는 큰 이점이 있습니다.

 

프런트엔드 개발자에게 OpenAPI 3.0은 단순한 문서 이상의 의미를 가지며, 백엔드와의 원활한 소통을 돕는 중요한 도구입니다.

실제 서비스에 적용할 때는 명세서 기반의 자동화, 코드 생성, 지속적인 배포 파이프라인 등 다양한 측면에서 활용할 수 있으니, 이를 적극적으로 도입하여 개발 효율성을 극대화해 보세요.

참고 자료

• OpenAPI Specification 3.0.3
• OpenAPI Generator
• Swagger UI
• Redoc
• Dredd
• Schemathesis