{
  "openapi": "3.0.3",
  "info": {
    "title": "API 작성 가이드 · 주문 조회·생성 예제",
    "version": "1.0.0",
    "description": "스펙브릿지 블로그의 가상 문서 작성 예시입니다. 실제 고객 데이터와 실제 API 서버는 없습니다."
  },
  "servers": [
    {
      "url": "https://example.invalid",
      "description": "실제 호출할 수 없는 예시 주소"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/orders/{orderId}": {
      "get": {
        "operationId": "getOrder",
        "summary": "본인 주문 단건 조회",
        "description": "로그인한 사용자가 본인 주문을 조회하는 가상 API입니다.",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "ORD-20261102-001"
          }
        ],
        "responses": {
          "200": {
            "description": "조회 성공",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                },
                "example": {
                  "orderId": "ORD-20261102-001",
                  "status": "PAID",
                  "totalAmount": 39000,
                  "currency": "KRW",
                  "orderedAt": "2026-11-02T09:00:00+09:00"
                }
              }
            }
          },
          "401": {
            "description": "인증 토큰을 확인하세요.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "인증 토큰을 확인하세요."
                }
              }
            }
          },
          "403": {
            "description": "조회 권한이 없습니다.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "FORBIDDEN",
                  "message": "조회 권한이 없습니다."
                }
              }
            }
          },
          "404": {
            "description": "주문을 찾을 수 없습니다.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ORDER_NOT_FOUND",
                  "message": "주문을 찾을 수 없습니다."
                }
              }
            }
          },
          "400": {
            "description": "주문 ID 형식을 확인하세요.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_ORDER_ID",
                  "message": "주문 ID 형식을 확인하세요."
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders": {
      "post": {
        "operationId": "createOrder",
        "summary": "주문 생성",
        "description": "가격은 서버가 계산하며 생성 직후 상태는 CREATED입니다. 결제 처리는 포함하지 않습니다.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrderRequest"
              },
              "example": {
                "productId": "SKU-1001",
                "quantity": 2
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "주문 생성 성공",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                },
                "example": {
                  "orderId": "ORD-20261102-002",
                  "status": "CREATED",
                  "totalAmount": 38000,
                  "currency": "KRW",
                  "orderedAt": "2026-11-02T09:10:00+09:00"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "생성된 주문의 상대 경로",
                "schema": {
                  "type": "string"
                },
                "example": "/v1/orders/ORD-20261102-002"
              }
            }
          },
          "400": {
            "description": "필수 값과 수량 범위를 확인하세요.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "필수 값과 수량 범위를 확인하세요."
                }
              }
            }
          },
          "401": {
            "description": "인증 토큰을 확인하세요.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "인증 토큰을 확인하세요."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "CreateOrderRequest": {
        "type": "object",
        "required": [
          "productId",
          "quantity"
        ],
        "properties": {
          "productId": {
            "type": "string",
            "description": "주문할 상품 ID"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "주문 수량"
          }
        }
      },
      "Order": {
        "type": "object",
        "required": [
          "orderId",
          "status",
          "totalAmount",
          "currency",
          "orderedAt"
        ],
        "properties": {
          "orderId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "CREATED",
              "PAID",
              "PREPARING",
              "SHIPPED",
              "CANCELLED"
            ]
          },
          "totalAmount": {
            "type": "integer",
            "minimum": 0,
            "description": "서버가 계산한 원 단위 총액"
          },
          "currency": {
            "type": "string",
            "enum": [
              "KRW"
            ]
          },
          "orderedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}