OpenAPI 파라미터 기술

OpenAPI 파라미터 기술 (Describing Parameters)

오퍼레이션 하나를 정의했다면, 그 오퍼레이션이 어떤 파라미터를 받는지도 적어야 해요. OpenAPI 파라미터는 name, 위치(in), 데이터 타입(schema 또는 content)으로 구성돼요.

출처: https://swagger.io/docs/specification/describing-parameters/

기본 형태는 이래요.

paths:
  /users/{userId}:
    get:
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get

파라미터가 위치할 수 있는 곳(in)은 네 가지예요.

  • path: URL 경로의 변수 부분. /users/{id}의 {id}처럼요. 경로 파라미터는 항상 required: true여야 해요.
  • query: 쿼리스트링. enum으로 허용 값을 제한할 수도 있어요(예: role을 user/poweruser/admin 중 하나로).
  • header: HTTP 헤더. Accept는 응답 컨텐츠 타입과, Authorization은 보안 스킴과 연결돼요.
  • cookie: 쿠키. 배열·객체는 form 스타일로 직렬화돼요. 쿠키 인증을 정의하려면 API key를 쓰는 걸 권장해요.

기본적으로 모든 요청 파라미터는 **선택(optional)**이에요. 필요하다면 required: true를 붙이고, 스키마에 nullable: true를 주면 null 값도 허용하는 파라미터를 표현해요(예: C#의 int?).

공통 파라미터는 두 곳에 모아 재사용할 수 있어요.

  • 한 경로의 모든 메서드에 공통이면 **경로 레벨 parameters**에 둬요(예: 경로의 {id}).
  • 여러 경로에서 쓰면 **components.parameters**에 정의하고 $ref로 참조해요.
components:
  parameters:
    offsetParam:
      in: query
      name: offset
      schema:
        type: integer
        minimum: 0
paths:
  /users:
    get:
      parameters:
        - $ref: "#/components/parameters/offsetParam"

주의할 점은 OpenAPI 3.0은 파라미터 의존성이나 상호 배타 파라미터를 지원하지 않아요. rdate가 start_date/end_date와 호환되지 않는다면, 그 제약을 파라미터 description에 문서화하고 실제 검증 로직은 응답이 400 Bad Request를 돌려주는 방식으로 처리해요.

더 알아보기