json - swagger中的API文档，需要验证

问题描述

我们的项目需要开放API给合作伙伴，所以我们只开放了一个API“创建订单”。我大摇大摆地创建了一个文档，让他们知道如何调用我们的“创建订单”服务。

经过多次修改，他们仍然声称无法根据我的文档创建成功的 API 调用。

我把我的API文档贴在这里让大家判断一下，我的文档有什么问题。请给我建议

{
  "swagger": "2.0",
  "info": {
      "description": "Core Platform",
      "version": "1.0.0",
      "title": "Core Platform"
  },
  "host": "test.apihost.com",
  "basePath": "/api/v1",
  "tags": [
      {
          "name": "order",
          "description": "Place an order"
      }
  ],
  "schemes": [
      "http"
  ],
  "paths": {
      "/order": {
          "post": {
              "tags": [
                  "order"
              ],
              "summary": "Create an order",
              "description": "",
              "operationId": "orderPost",
              "consumes": [
                  "application/json"
              ],
              "responses": {
                  "200": {
                      "description": "Success"
                  }
              },
              "parameters": [
                  {
                      "in": "body",
                      "name": "body",
                      "description": "Order object",
                      "required": true,
                      "schema": {
                          "$ref": "#/definitions/Order"
                      }
                  }
              ]
          }
      }
  },
  "definitions": {
      "Order": {
          "type": "object",
          "properties": {
              "retailer_id": {
                  "type": "integer",
                  "example": 123
              },
              "salesperson_id": {
                  "type": "integer",
                  "example": 42
              },
              "store_id": {
                  "type": "integer",
                  "example": 456
              },
              "line_items": {
                  "type": "object",
                  "example": [
                      {
                          "identifier": "bLCRZB9mV42nf",
                          "markup_rate": 0.3,
                          "markup_amount": 300,
                          "quantity": 1,
                          "retail_price": 1300,
                          "type": "Diamond",
                          "wholesale_price": 1000
                      },
                      {
                          "identifier": "zDWMZB9mV08zz",
                          "markup_rate": 0.2,
                          "markup_amount": 140,
                          "quantity": 1,
                          "retail_price": 840,
                          "type": "Setting",
                          "wholesale_price": 700
                      },
                      {
                          "currency": "USD",
                          "shipping": 0,
                          "subtotal": 2140,
                          "discount": 100,
                          "total": 2040,
                          "wholesale_subtotal": 1700
                      }
                  ]
              },
              "customer": {
                  "type": "object",
                  "example": {
                      "first_name": "Ranl",
                      "last_name": "Gao",
                      "email": "customer@gmail.com",
                      "phone": "888-555-1212"
                  }
              },
              "store": {
                  "type": "object",
                  "example": {
                      "company": "Store Name",
                      "address1": "123 Fake Street",
                      "address2": "123 Fake Street",
                      "phone": "777-777-7777",
                      "city": "Fakecity",
                      "province": "Shanghai",
                      "country": "China",
                      "postal_code": "K2P 1L4"
                  }
              },
              "shipping_address": {
                  "type": "object",
                  "example": {
                      "company": "Diamond Exchange",
                      "first_name": "Jane",
                      "last_name": "Smith",
                      "address1": "123 Fake Street",
                      "address2": "123 Fake Street",
                      "phone": "777-777-7777",
                      "city": "Fakecity",
                      "province": "Shanghai",
                      "country": "China",
                      "postal_code": "K2P 1L4"
                  }
              },
              "transactions": {
                  "type": "object",
                  "example": [
                      {
                          "type": "voucher",
                          "status": "issued",
                          "voucher_id": "xyzabc1234",
                          "amount": 1300
                      }
                  ]
              }
          }
      }
  }
}

标签： jsonrestapiswaggerdocument

json - swagger中的API文档，需要验证

问题描述

解决方案

推荐阅读