1. 라이브러리
  2. HTTP와 웹
  3. API와 웹 서비스

OpenAPI 문서화

업데이트됨 1개월 전

모든 개발자는 이 느낌을 안다: 문서는 한 가지를 말하는데, API는 다른 일을 한다. 예제를 그대로 따랐는데 400 오류가 뜬다. 실제 구현 코드를 파고들어 보면 문서가 몇 달째 업데이트되지 않았다는 걸 발견한다. 누군가 필수 필드를 바꿨는데 README 업데이트를 깜빡한 것이다.

이것이 문서 표류(documentation drift)다. 그리고 우리는 어쩐지 이걸 당연한 일로 받아들이게 되었다.

OpenAPI Specification이 존재하는 이유는, 거짓말할 수 있는 문서는 결국 거짓말을 하기 때문이다. OpenAPI 문서는 여러분의 API를 설명한다—엔드포인트, 요청 형식, 응답 스키마, 인증, 오류—이 모든 것을 기계가 읽을 수 있는 YAML 또는 JSON으로. 하지만 진짜 중요한 건 이것이다: 기계가 읽을 수 있으니, 기계가 이를 강제할 수 있다. 문서와 진실이 동일한 것이 된다.

진실의 구조

OpenAPI 문서는 특정한 구조를 갖는다. 이를 이해한다는 것은 "기계가 읽을 수 있는 API 명세"가 실제로 어떻게 생겼는지를 이해하는 것이다.

Info는 API를 식별한다:

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users in the system

Servers는 API가 어디에 있는지 선언한다:

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

Paths는 모든 엔드포인트와 그것이 하는 일을 설명한다:

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer

Components는 재사용 가능한 요소들을 정의한다—스키마, 보안 스키마, 공통 파라미터:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        created_at:
          type: string
          format: date-time
          
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

$ref 문법을 사용하면 같은 내용을 반복하는 대신 정의를 참조할 수 있다. User 스키마를 한 번만 바꾸면, 그것을 사용하는 모든 엔드포인트가 자동으로 업데이트된다. 대규모 API 문서를 일관성 있게 유지하는 방법이 바로 이것이다.

오퍼레이션 상세

각 엔드포인트 오퍼레이션에는 완전한 설명이 붙는다:

/users/{userId}:
  get:
    summary: Get a user by ID
    operationId: getUserById
    tags:
      - Users
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      '200':
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
    security:
      - bearerAuth: []

operationId는 클라이언트 코드를 생성할 때 함수 이름이 된다. 태그는 관련 오퍼레이션을 묶어준다. security는 인증 요구사항을 지정한다. 성공과 실패를 포함한 모든 가능한 응답이 정확한 형태와 함께 문서화된다.

기계 가독성이 열어주는 가능성

기계가 여러분의 API 명세를 읽을 수 있게 되면, 사람이 절대 할 수 없었던 일들을 할 수 있다.

인터랙티브 문서화 도구인 Swagger UI 같은 것들은 OpenAPI 문서를 탐색하고 실행할 수 있는 인터페이스로 렌더링한다. 개발자들은 같은 공간에서 문서를 읽고 API를 테스트할 수 있다. "Execute"를 클릭하면 실제 응답을 볼 수 있다. curl 명령어도 필요 없고, Postman 설정도 필요 없다.

클라이언트 생성은 하나의 OpenAPI 문서에서 40개 이상의 언어로 SDK를 생성한다:

openapi-generator generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./client

결과물로 나오는 건 타입이 지정된 클라이언트다—모든 엔드포인트가 메서드이고, 모든 요청 본문이 타입이며, 모든 응답이 예측 가능하다. API가 바뀌면 클라이언트를 재생성하면 된다. 수동 업데이트도 없고, 버전 불일치도 없다.

유효성 검사 미들웨어는 명세와 일치하지 않는 요청을 애플리케이션 코드에 도달하기 전에 거부할 수 있다. OpenAPI 문서에서 email이 필수이고 이메일 형식이어야 한다고 명시되어 있다면, 유효한 이메일이 없는 요청은 자동으로 거부된다. 애플리케이션 코드는 잘못된 입력을 절대 보지 않는다.

목 서버는 백엔드 구현 없이 명세의 예제 데이터로 응답한다:

prism mock openapi.yaml

프론트엔드 팀은 API가 존재하기 전에 그것에 맞춰 개발할 수 있다. 계약이 명세이고, 목 서버가 그것을 지킨다.

계약 테스트는 실제 구현이 명세와 일치하는지 검증한다. 코드가 문서에서 벗어나면 테스트가 실패한다. 문서의 거짓말이 CI 실패가 된다.

설계 우선 vs. 코드 우선

OpenAPI 문서에 도달하는 방법에는 두 가지가 있다.

**설계 우선(Design-first)**은 구현 전에 명세를 먼저 작성한다. API를 하나의 제품으로 생각한다: 소비자에게 무엇이 필요한가? 가장 깔끔한 인터페이스는 무엇인가? 코드를 작성하기 전에 설계에 대한 피드백을 받을 수 있다. 명세에서 서버 스텁을 생성하고 구현을 채워 넣는다.

이 방법이 더 좋은 API를 만든다. 하지만 코딩 전에 생각을 먼저 해야 하는데, 일부 팀에서는 이게 불편하게 느껴지기도 한다.

**코드 우선(Code-first)**은 API를 먼저 구현한 다음, 코드 어노테이션에서 OpenAPI 문서를 생성한다. 시작은 빠르지만, 명세가 의도적인 설계가 아닌 구현 결정의 산물이 된다. 문서 표류가 슬그머니 뒷문으로 돌아온다—이번에는 어노테이션이 코드에서 벗어나는 형태로.

공개 API, 소비자가 많은 API, 안정적이어야 하는 API 등 중요한 API를 가진 대부분의 팀은 설계 우선이 초기 투자 가치가 있다고 생각한다.

도구 생태계

편집기: Swagger Editor, Stoplight Studio—유효성 검사와 미리보기가 있는 전문 환경.

문서화: Swagger UI, Redoc, RapiDoc—명세를 아름답고 인터랙티브한 문서로 렌더링.

생성기: OpenAPI Generator, Swagger Codegen—클라이언트와 서버 스텁 생성.

유효성 검사기: Spectral—명세의 오류와 스타일 위반 린팅.

게이트웨이: Kong, AWS API Gateway—명세를 임포트해서 라우팅과 유효성 검사 구성.

표준이 있기 때문에 생태계가 존재한다. 기계가 읽을 수 있는 형식은 수동 문서화가 결코 가능하게 할 수 없는 방대한 도구 생태계를 가능하게 한다.

OpenAPI가 할 수 없는 것들

OpenAPI는 REST API를 설명한다. API가 GraphQL이거나, WebSocket 중심이거나, 리소스와 HTTP 메서드에 매핑되지 않는 패턴을 따른다면 OpenAPI는 맞지 않는다.

대규모 API는 큰 문서를 만든다. 수백 개의 엔드포인트는 수천 줄의 YAML을 의미한다. 구성 자체가 하나의 도전이 된다.

생성된 코드는 생성된 코드다. 여러분의 스타일과 맞지 않을 수 있고, 원하지 않는 의존성이 포함될 수 있으며, 프로덕션 준비가 되기 전에 커스터마이징이 필요할 수 있다.

그리고 문서는 여전히 유지 관리해야 한다. 설계 우선이 도움이 되고, 유효성 검사가 도움이 되지만, API가 발전함에 따라 누군가가 명세를 정확하게 유지해야 한다.

이러한 한계에도 불구하고, OpenAPI는 REST API 문서화의 표준으로 남아 있다. 대안—거짓말하는 문서—은 더 나쁘다.

OpenAPI에 관한 자주 묻는 질문

OpenAPI와 Swagger의 차이는 무엇인가?

Swagger가 원래 이름이었다. 2015년에 이 명세가 OpenAPI Initiative에 기부되면서 OpenAPI Specification이 되었다. Swagger는 이제 명세 자체가 아니라 도구(Swagger UI, Swagger Editor)를 가리킨다.

OpenAPI 문서에 YAML과 JSON 중 어느 것을 써야 하는가?

YAML이 더 읽기 쉽고, 손으로 작성하는 명세에는 대부분의 팀이 YAML을 사용한다. JSON은 생성된 명세나 도구가 JSON을 선호할 때 더 잘 맞는다. 내용은 동일하고 문법만 다를 뿐이다.

OpenAPI로 API 버전 관리를 어떻게 처리하는가?

각 API 버전마다 별도의 OpenAPI 문서를 유지한다(v1.yaml, v2.yaml). info.version 필드는 명세 버전을 추적하고, URL 경로나 헤더가 일반적으로 API 버전 관리를 처리한다.

기존 코드에서 OpenAPI 명세를 생성할 수 있는가?

그렇다—대부분의 프레임워크에는 어노테이션이나 데코레이터에서 OpenAPI를 생성하는 라이브러리가 있다. 하지만 그 결과 명세는 의도적인 API 설계가 아닌 구현 결정을 반영한다. 완성된 결과물이 아닌 출발점이다.

다음

API란 무엇인가?

이 페이지가 도움이 되었나요?

😔
🤨
😃
OpenAPI 문서화 • 라이브러리 • Connected