📒Paths and Operations

OpenAPI에서 paths는 /users 등의 endpoint를 의미한다.

Operations는 paths에 대한 GET, POST, DELETE 등의 HTTP 메서드다.

✔️Paths

API paths와 operations는 API 명세서의 global paths section에 정의해야 합니다.

paths:
  /ping:
    ...
  /users:
    ...
  /users/{id}:
    ...

모든 paths들은 api server url의 상대 경로입니다. full request URL은 <server-url>/path가 된다.

하지만 global servers는 path level 혹은 operation level에 의해 override 될 수 있다.

paths마다 문서화 목적으로 summary 그리고 description을 적을 수 있다.

이는 선택사항이며, 이 path와 관련된 모든 operation들의 정보를 나타내기 위해 적는다.

paths:
  /users/{id}:
    summary: Represents a user
    description: >
      This resource represents an individual user in the system.
      Each user is identified by a numeric `id`.
    get:
      ...
    patch:
      ...
    delete:
      ...

✔️Path Templating

URL의 path parameters를 표현하기 위해 괄호{}를 사용할 수 있다.

클라이언트는 api를 호출할 때 반드시 적절한 path parameter 값을 넘겨줘야 한다. (ex. /users/5, /users/12)

/users/{id}
/organizations/{orgId}/members/{memberId}
/report.{format}

✔️Operations

각 path에 대해서 path가 지원하는 HTTP methods를 정의해야 한다.

OpenAPI 3.0은 다음과 같은 HTTP methods를 지원한다.

get, post, put, patch, delete, head, options, trace

하나의 path는 여러 operations를 지원할 수 있다.

OpenAPI는 operation을 path와 HTTP method의 조합으로 구분한다. 따라서 같은 path에 대해 두 개의 GET, 두 개의 POST는 불가능하다.

paths:
  /users/{id}:
    get:
      tags:
        - Users
      summary: Gets a user by ID.
      description: >
        A detailed description of the operation.
        Use markdown for rich text representation,
        such as **bold**, *italic*, and [links](https://swagger.io).
      operationId: getUserById
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      externalDocs:
        description: Learn more about user operations provided by this API.
        url: http://api.example.com/docs/user-operations/
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      required:
        - id
        - name

Operations는 문서화 목적으로 몇몇의 elements를 제공한다. 이를 사용하는 것은 선택사항이다.

• summary, description
description은 여러 줄로 작성 가능하며 마크다운 표기법을 따른다.
• tags
  리소스 단위로 혹은 다른 적합한 단위로 operations를 논리적으로 그룹화하기 위해 사용한다.
• externalDocs
  추가적인 문서(정보)를 가지고 있는 외부 리소스의 참조를 적기위해 사용한다.

✔️Operation parameters

OpenAPI 3.0에서는 path, query string, headers, cookies를 통해 operation parameters를 받을 수 있도록 지원한다.

request body 또한 정의할 수 있다.

✔️Query String in Paths

쿼리 스트링은 paths에 절대 포함되어서는 안된다.

📌예시

incorrect

paths:
  /users?role={role}:

correct

paths:
  /users:
    get:
      parameters:
        - in: query
          name: role
          schema:
            type: string
            enum: [user, poweruser, admin]
          required: true

이는 쿼리 스트링만으로 구분되는 여러 개의 paths는 존재할 수 없음을 의미한다.

GET /users?firstName=value&lastName=value
GET /users?role=value

OpenAPI operation이 unique함을 구분하기 위해서 path와 HTTP method의 조합을 사용하기 때문이다.

위에 처럼 추가 쿼리스트링 만으로는 operation을 unique하게 구분할 수 없다.

✔️operationId

operationId는 operation을 구별하기 위해 사용하는 unique한 string이다.
operationId는 API에 정의된 모든 operation을 구분할 수 있도록 unique해야 한다.

반드시 작성할 필요는 없다.

/users:
  get:
    operationId: getUsers
    summary: Gets all users
    ...
  post:
    operationId: addUser
    summary: Adds a new user
    ...
/user/{id}:
  get:
    operationId: getUserById
    summary: Gets a user by user ID
    ...

✔️Deprecated Operations

특정 operations들을 deprecated 되었다고 표시할 수 있다.

/pet/findByTags:
  get:
    deprecated: true

✔️Overriding Global Servers

global servers 배열은 path level 혹은 operation level의 url에 의해 override 될 수 있다.

특정 endpoint들이 다른 서버나 다른 base path를 사용하는 경우 유용하다.

• Different base URL for file upload and download operations.
• Deprecated but still functional endpoints.

servers:
  - url: https://api.example.com/v1
paths:
  /files:
    description: File upload and download operations
    servers:
      - url: https://files.example.com
        description: Override base path for all operations with the /files path
    ...
  /ping:
    get:
      servers:
        - url: https://echo.example.com
          description: Override base path for the GET /ping operation