📒Parameter Serialization

Serialization은 data structures 혹은 객체를 전송 가능한 형태(데이터스트림)로 만들고 후에 재구성하는 것을 말한다.

OpenAPI 3.0은 배열과 객체를 operation parameters(path, query, header, cookie)로 사용할 수 있도록 지원하고 어떻게 serialization할지 명시하도록 한다.

serialization 방법은 style과 explode 키워드로 결정된다.

• style은 multiple values를 어떻게 구분할 것인지 결정한다.
  path, query, header, cookie에 따라 가능한 style이 다르다.

• explode(true/false)는 배열과 객체의 각 요소나 프로퍼티에 대해 별도의 매개변수를 생성해야 하는지 여부를 명시한다.

OpenAPI 직렬화는 RFC 6570에 정의된 URI template 패턴들의 일부를 기반으로 한다.

✔️Path Parameters

path parameters는 다음의 style 값들을 지원한다.

• simple - 기본값이며 콤마로 구분된 값들이다. {param_name} URI template
• label - dot-prefixed 값들이다. label expansion으로도 알려져 있다. {.param_name} URI template
• matrix - semicolon-prefixed 값들이다. path-style expansion으로도 알려져 있다. {;param_name} URI template

기본 직렬화 방법은 style: simple과 explode: false다.

별이 붙은 것이 기본 값이다.

✔️Query Parameters

query parameters는 다음의 style 값들을 지원한다.

• form - 기본값이며, 엠퍼센트로 구분된 값들이다. form-style expansion으로도 알려져 있다. {?param_name} URI template.
• spaceDelimited - 공백으로 구분된 배열 값들이다.OpenAPI 2.0의 collectionFormat: ssv와 동일하다. non-exploded arrays(explode: false)에만 적용된다.
• pipeDelimited - 파이프라인으로 구분된 배열 값들이다.OpenAPI 2.0의 collectionFormat: pipes와 동일하다. non-exploded arrays(explode: false)에만 적용된다.
• deepObject - 중첩 되지 않은 simple 객체들은paramName[prop1]=value1&paramName[prop2]=value2&... 이렇게 직렬화된다.

기본 직렬화 방법은 style: form이고 explode: true다.

별표가 기본값이다.

alloweReversed 키워드는 :/?#[]@!$&'()*+,;= 이 값들이 parameter 값으로 쓸 때 그대로 허용할지 percent-encoded 되도록 할지를 결정한다.

기본적으로 alloReversed: false이다. 그리고 기본적으로 percent-encoded된다. / -> %2F (or %2f) 로 encoding 되기 때문에 quotes/h2g2.txt -> quotes%2Fh2g2.txt로 전송된다.

✔️Header Parameters

Header parameters는 항상 style: simple이다. explode 키워드 값이 객체 직렬화를 위해 선택적으로 사용된다.

✔️Cookie Parameters

cookie parameters는 항상 style: form이다. explode 키워드 값이 배열과 객체 직렬화를 위해 선택적으로 사용된다.

✔️Serialization and RFC 6570

아래 예시는 path를 /users{id} 처럼 할 때 정의하는 방법이다.

paths:
  # /users;id=3;id=4?metadata=true
  /users{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: array
            items:
              type: integer
            minItems: 1
          style: matrix
          explode: true
        - in: query
          name: metadata
          schema:
            type: boolean
          # Using the default serialization for query parameters:
          # style=form, explode=false, allowReserved=false
      responses:
        '200':
          description: A list of users