OpenAPI 경로와 오퍼레이션

OpenAPI 경로와 오퍼레이션 (Paths and Operations)

OpenAPI에서 **경로(path)**는 API가 노출하는 엔드포인트(예: /users, /reports/summary/)이고, **오퍼레이션(operation)**은 그 경로를 다루는 HTTP 메서드(GET, POST, DELETE 등)예요. 이 둘을 어떻게 정의하는지가 명세 작성의 핵심이에요.

출처: https://swagger.io/docs/specification/paths-and-operations/

모든 경로·오퍼레이션은 스펙의 전역 paths 섹션에 정의해요. 경로는 서버 URL 기준이라서 전체 요청 URL은 <server-url>/path가 돼요.

paths:
  /users/{id}:
    summary: Represents a user
    get:
      tags:
        - Users
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

{id}처럼 중괄호로 감싼 부분은 **경로 템플릿(path templating)**이에요. 클라이언트는 호출할 때 /users/5처럼 실제 값을 채워 넣어요. /users/{id}, /organizations/{orgId}/members/{memberId} 같은 다중 파라미터도 가능해요.

오퍼레이션으로 지원하는 HTTP 메서드는 get, post, put, patch, delete, head, options, trace예요. 한 경로에 여러 메서드를 둘 수 있고(GET /users는 목록, POST /users는 생성), 각 오퍼레이션엔 summary·description·tags·externalDocs 같은 문서화 필드를 달 수 있어요.

operationId는 오퍼레이션을 식별하는 유일한 문자열이에요. 코드 생성기가 메서드 이름을 만들 때 쓰거나, Links가 연결 대상을 operationId로 참조할 때 써요. 쿼리스트링은 오퍼레이션을 구별하는 요소가 아니기 때문에, 쿼리만 다른 두 경로는 같은 오퍼레이션으로 취급돼요 — 서로 다른 경로를 써야 해요. 전역 servers는 경로 레벨이나 오퍼레이션 레벨에서 덮어쓸 수도 있어요.

더 알아보기