Openapi Spec Patterns

# Tag 기반 그룹핑 → SDK 클래스 매핑
paths:
  /users:
    get:
      tags: [Users]         # → UsersClient.list()
    post:
      tags: [Users]         # → UsersClient.create()
  /users/{id}:
    get:
      tags: [Users]         # → UsersClient.get(id)
    put:
      tags: [Users]         # → UsersClient.update(id, data)
    delete:
      tags: [Users]         # → UsersClient.delete(id)
  /users/{id}/orders:
    get:
      tags: [Users, Orders] # → UsersClient.listOrders(id)

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: https://auth.example.com/authorize
        tokenUrl: https://auth.example.com/token
        scopes:
          read: Read access
          write: Write access

# 패턴 1: Offset-based
parameters:
  - name: offset
    in: query
    schema: { type: integer }
  - name: limit
    in: query
    schema: { type: integer, default: 20 }

# 패턴 2: Cursor-based
parameters:
  - name: cursor
    in: query
    schema: { type: string }
  - name: limit
    in: query
    schema: { type: integer }

# 패턴 3: Page-based
parameters:
  - name: page
    in: query
    schema: { type: integer }
  - name: per_page
    in: query
    schema: { type: integer }

# 표준 에러 구조 추출
responses:
  '400':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        code: { type: string }
        message: { type: string }
        details: { type: array, items: { $ref: '#/components/schemas/ErrorDetail' } }

# 순환: User → Order → User
User:
  properties:
    orders:
      type: array
      items: { $ref: '#/components/schemas/Order' }
Order:
  properties:
    user: { $ref: '#/components/schemas/User' }  # 순환!

# 해결: Lazy Reference
# TypeScript: type User = { orders: () => Order[] }
# Python: User = ForwardRef('User')

# allOf → 인터섹션 (상속/확장)
UpdateUser:
  allOf:
    - $ref: '#/components/schemas/BaseUser'
    - type: object
      properties:
        password: { type: string }
# → class UpdateUser extends BaseUser { password?: string }

# oneOf → 유니온 (택일)
Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
  discriminator:
    propertyName: petType
# → type Pet = Cat | Dog (discriminated union)

# anyOf → 유연한 유니온
Filter:
  anyOf:
    - type: string
    - type: integer
    - type: array
      items: { type: string }
# → type Filter = string | number | string[]

# Query → SDK read 메서드
type Query {
    user(id: ID!): User        # → client.users.get(id)
    users(first: Int, after: String): UserConnection  # → client.users.list()
}

# Mutation → SDK write 메서드
type Mutation {
    createUser(input: CreateUserInput!): User  # → client.users.create(input)
    updateUser(id: ID!, input: UpdateUserInput!): User
}

# Connection 패턴 → 자동 페이지네이션
type UserConnection {
    edges: [UserEdge!]!
    pageInfo: PageInfo!
}

service UserService {
    rpc GetUser (GetUserRequest) returns (User);           // → client.getUser(id)
    rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
    rpc CreateUser (CreateUserRequest) returns (User);
    rpc StreamUsers (StreamRequest) returns (stream User); // → 스트리밍 API
}