Swagger创建订单API文档问题排查：合作伙伴调用失败求助

Alright, let’s break down the critical problems in your Swagger documentation that are almost certainly tripping up your partners, plus targeted fixes to get things working smoothly:

1. Mismatched Data Types vs. Examples #

This is a top culprit—your schema defines some fields as object but provides array examples, which creates total confusion for API clients:

• line_items: Marked as type: object, but the example is an array of line items mixed with order-level metadata (like currency, total).
• transactions: Marked as type: object, but the example is an array of transaction objects.

Fix:
Correct the type to array for both fields, and move order-level fields (currency, shipping, subtotal, etc.) to the top-level Order object where they belong:

"line_items": {
  "type": "array",
  "description": "List of items included in the order",
  "items": {
    "type": "object",
    "properties": {
      "identifier": { "type": "string", "example": "bLCRZB9mV42nf" },
      "markup_rate": { "type": "number", "example": 0.3 },
      "markup_amount": { "type": "integer", "example": 300 },
      "quantity": { "type": "integer", "example": 1 },
      "retail_price": { "type": "integer", "example": 1300 },
      "type": { "type": "string", "example": "Diamond" },
      "wholesale_price": { "type": "integer", "example": 1000 }
    }
  }
},
"transactions": {
  "type": "array",
  "description": "List of payment transactions associated with the order",
  "items": {
    "type": "object",
    "properties": {
      "type": { "type": "string", "example": "voucher" },
      "status": { "type": "string", "example": "issued" },
      "voucher_id": { "type": "string", "example": "xyzabc1234" },
      "amount": { "type": "integer", "example": 1300 }
    }
  }
},
// Move order-level fields here
"currency": { "type": "string", "example": "USD" },
"shipping": { "type": "integer", "example": 0 },
"subtotal": { "type": "integer", "example": 2140 },
"discount": { "type": "integer", "example": 100 },
"total": { "type": "integer", "example": 2040 },
"wholesale_subtotal": { "type": "integer", "example": 1700 }

2. Missing Required Field Definitions #

Your Order schema doesn’t specify which fields are required. Partners might be omitting critical fields (like retailer_id, line_items, customer) without realizing it, leading to failed requests.

Fix:
Add a required array to the Order definition to explicitly list mandatory fields:

"Order": {
  "type": "object",
  "required": ["retailer_id", "line_items", "customer", "shipping_address"],
  "properties": {
    // ... existing properties ...
  }
}

3. Incomplete Response Documentation #

Right now, you only have a generic 200: Success response with no details. Partners have no idea what a successful response looks like, and no guidance on error responses (e.g., 400 for bad input, 401 for auth issues, 500 for server errors).

Fix:
Add structured response schemas and examples for both success and common errors:

"responses": {
  "200": {
    "description": "Order created successfully",
    "schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string", "example": "ORD-123456" },
        "status": { "type": "string", "example": "created" },
        "created_at": { "type": "string", "format": "date-time", "example": "2024-05-20T14:30:00Z" }
      }
    }
  },
  "400": {
    "description": "Invalid request body (missing required fields or invalid data)",
    "schema": {
      "type": "object",
      "properties": {
        "error_code": { "type": "string", "example": "INVALID_INPUT" },
        "message": { "type": "string", "example": "Missing required field: retailer_id" },
        "details": { "type": "array", "items": { "type": "string" } }
      }
    }
  },
  "401": {
    "description": "Unauthorized (invalid API key or credentials)"
  }
}

4. Vague & Misleading Examples #

• Duplicate address values (e.g., store.address1 and store.address2 are identical) confuse partners about what each field is for.
• Typos like first_name: "Ranl" (likely a typo for "Raul" or "Ran") make examples untrustworthy.
• The store field in the Order object is redundant since you already have store_id at the top level—this creates ambiguity (should partners send both? Which takes precedence?).

Fix:

• Update examples to use distinct, realistic values (e.g., address1: "123 Fake Street", address2: "Suite 456").
• Fix typos in examples.
• Remove the redundant store object (or clarify if it’s meant to override the store_id data).

5. Security & Documentation Gaps #

• Using http in schemes is insecure for order data—partners might be hesitant to send sensitive customer/transaction data over unencrypted connections.
• The post operation’s description is empty; add clear context about what the API does, any prerequisites (like API key auth), and constraints (e.g., maximum line items per order).

Fix:

• Change schemes to ["https"] (ensure your test endpoint supports HTTPS).
• Fill in the operation description:

"post": {
  "tags": ["order"],
  "summary": "Create an order",
  "description": "Creates a new retail order with line items, customer details, shipping address, and transaction information. Requires a valid API key in the Authorization header. Maximum 50 line items per order.",
  // ... rest of the operation ...
}

6. Missing Authentication Details #

There’s no mention of how partners should authenticate their requests (e.g., API key, OAuth2). If your API requires auth, this omission will definitely cause failed calls.

Fix:
Add a securityDefinitions section at the top level of your Swagger doc, and link it to the post operation:

"securityDefinitions": {
  "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "Authorization"
  }
},
"security": [{"ApiKeyAuth": []}]

内容的提问来源于stack exchange，提问作者Yang Han