Question

我已经查看了其他一些相关问题，但我似乎无法找到我正在寻找的东西。这是一个示例JSON有效负载发送到API我写的：

{
    "publishType": "Permitable",
    "electricalPanelCapacity": 0.0,
    "roofConstruction": "Standard/Pitched",
    "roofType": "Composition Shingle",
    "systemConstraint": "None",
    "addedCapacity": 0.0,
    "isElectricalUpgradeRequired": false,
    "cadCompletedBy": "94039",
    "cadCompletedDate": "2017-02-01T02:18:15Z",
    "totalSunhourDeficit": 5.0,
    "designedSavings": 5.0,
    "isDesignedWithinTolerance": "N/A",
    "energyProduction": {
        "january": 322.40753170051255,
        "february": 480.61501312589826,
        "march": 695.35215022905118,
        "april": 664.506907341219,
        "may": 877.53769491124172,
        "june": 785.56924358327,
        "july": 782.64347308783363,
        "august": 760.1123565793057,
        "september": 574.67050827435878,
        "october": 524.53797441350321,
        "november": 324.31132291046379,
        "december": 280.46921069200033
    },
    "roofSections": [{
        "name": "North East Roof 4",
        "roofType": "Composition Shingle",
        "azimuth": 55.678664773137086,
        "tilt": 15.0,
        "solmetricEstimate": 510.42831656979456,
        "shadingLoss": 14.0,
        "systemRating": 580.0,
        "sunHours": 0.88004882167205956,
        "moduleCount": 2,
        "modules": [{
            "moduleRating": 290.0,
            "isovaPartNumber": "CDS-MON-007070",
            "partCount": 2
        }]
    }, {
        "name": "South West Roof 3",
        "roofType": "Composition Shingle",
        "azimuth": 235.67866481720722,
        "tilt": 38.0,
        "solmetricEstimate": 3649.1643776261653,
        "shadingLoss": 59.0,
        "systemRating": 5220.0,
        "sunHours": 0.69907363556056812,
        "moduleCount": 18,
        "modules": [{
            "moduleRating": 290.0,
            "isovaPartNumber": "CDS-MON-007070",
            "partCount": 18
        }]
    }, {
        "name": "South East Roof",
        "roofType": "Composition Shingle",
        "azimuth": 145.67866477313709,
        "tilt": 19.0,
        "solmetricEstimate": 2913.1406926526984,
        "shadingLoss": 31.0,
        "systemRating": 2900.0,
        "sunHours": 1.0045312733285168,
        "moduleCount": 10,
        "modules": [{
            "moduleRating": 290.0,
            "isovaPartNumber": "CDS-MON-007070",
            "partCount": 10
        }]
    }],
    "SystemConfiguration": {
        "inverters": [{
            "isovaPartNumber": "ENP-INV-007182",
            "partCount": 30
        }]
    }
}

描述所有开始参数很简单。

/post/new-cad/{serviceNumber}:
    post:
      summary: Publish a new CAD record.
      description: Creates a new CAD record under the provided service number and returns the name of the new CAD record, the unique SF ID, and the deep link URL for Salesforce.
      parameters:
        - name: serviceNumber
          in: path
          description: The service number for the solar project you're interested in publishing to.
          required: true
          type: string
        - name: publishType
          in: formData
          description: The type of CAD record to publish (Proposal, Permitable, or AsBuilt).
          required: true
          type: string
        - name: electricalPanelCapacity
          in: formData
          required: true
          type: number
          format: double
        - name: roofConstruction
          in: formData
          description: New, Flat Roof, Open Beam, Standard/Pitched
          required: true
          type: string
        - name: roofType
          in: formData
          description: Composition Shingle, Membrane (Rubber, TPO, PVC, EPDM), Metal - Corrugated (S-Curve), Metal - Standing Seam, Metal - Trapezoidal, Multi Roof Type, Rolled Comp, Silicone, Tar & Gravel, Tile - Flat, Tile - S-Curve, or Tile - W-Curve
          type: string
        - name: systemConstraint
          in: formData
          description: Usage, None, Roof, Electrical, Shading, or 10kW Max
          required: true
          type: string
        - name: addedCapacity
          in: formData
          required: true
          type: number
          format: double
        - name: isElectricalUpgradeRequired
          in: formData
          type: boolean
        - name: cadCompletedBy
          in: formData
          description: Employee ID of record author.
          type: number
          required: true
        - name: cadCompletedDate
          in: formData
          description: The date the CAD record was completed.
          type: string
          format: date
          required: true
        - name: totalSunhourDeficit
          in: formData
          type: number
          format: double
        - name: designedSavings
          in: formData
          type: number
          format: double
        - name: isDesignedWithinTolerance
          in: formData
          type: string
          description: Yes, No, or N/A

并在Swagger-UI中产生预期结果：

但是现在我正在努力解决上面示例JSON有效负载的最后部分问题。我不确定如何表达energyProduction密钥，该密钥是一年中每个月的密钥对象。我还不确定如何描述roofSections这是一个对象数组，systemConfiguration是一个具有属性inverters的对象，其值是一个对象数组。

我过了swagger documentation但我还是很困惑，希望也许有人可以向我解释一些事情。

Answer 1

我明白了。结果formData不是我应该用于我的参数。相反，我需要使用body并定义将填充正文的JSON结构。以下是使用带有对象模式的body参数的完整设计文件，并描述了所有嵌套对象和数组。

 /new-cad/{serviceNumber}:
    post:
      summary: Publish a new CAD record.
      description: Creates a new CAD record under the provided service number and returns the name of the new CAD record, the unique SF ID, and the deep link URL for Salesforce.
      parameters:
        - name: serviceNumber
          in: path
          description: The service number for the solar project you're interested in publishing to.
          required: true
          type: string
        - name: cadData
          in: body
          description: A JSON payload containing the data required to publish a new CAD record.
          required: true
          schema:
            type: object
            properties:
              publishType:
                type: string
                default: "Proposal"
                enum: ["Proposal","Permitable","AsBuilt"]
              electricalPanelCapacity:
                type: number
              roofConstruction:
                type: string
                default: "New"
                enum: ["New","Flat Roof","Open Beam","Standard/Pitched"]
              roofType:
                type: string
                enum: ["Composition Shingle","Membrane (Rubber, TPO, PVC, EPDM)","Metal - Corrugated (S-Curve)","Metal - Standing Seam","Metal - Trapezoidal","Multi Roof Type","Rolled Comp","Silicone","Tar & Gravel","Tile - Flat","Tile - S-Curve","Tile - W-Curve"]
              systemConstraint:
                type: string
                default: "None"
                enum: ["None","Usage","Roof","Electrical","Shading","10kW Max"]
              addedCapacity:
                type: number
                default: 0
              isElectricalUpgradeRequired: 
                type: boolean
              cadCompletedBy:
                type: string
              cadCompletedDate:
                type: string
              totalSunhourDeficit:
                type: number
              designedSavings:
                type: number
              isDesignedWithinTolerance:
                type: string
                default: "N/A"
                enum: ["N/A","Yes","No"]
              energyProduction:
                type: object
                properties:
                  january:
                    type: number
                  february:
                    type: number
                  march:
                    type: number
                  april:
                    type: number
                  may:
                    type: number
                  june:
                    type: number
                  july:
                    type: number
                  august:
                    type: number
                  september:
                    type: number
                  october:
                    type: number
                  november:
                    type: number
                  december:
                    type: number
              roofSections:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    roofType:
                      type: string
                      enum: ["Composition Shingle","Membrane (Rubber, TPO, PVC, EPDM)","Metal - Corrugated (S-Curve)","Metal - Standing Seam","Metal - Trapezoidal","Multi Roof Type","Rolled Comp","Silicone","Tar & Gravel","Tile - Flat","Tile - S-Curve","Tile - W-Curve"]
                    azimuth:
                      type: number
                    tilt:
                      type: number
                    solmetricEstimate:
                      type: number
                    shadingLoss:
                      type: number
                    systemRating:
                      type: number
                    sunHours:
                      type: number
                    moduleCount:
                      type: integer
                    modules:
                      type: array
                      items:
                        type: object
                        properties:
                          moduleRating:
                            type: number
                          isovaPartNumber:
                            type: string
                          partCount:
                            type: integer
              systemConfiguration:
                type: object
                properties:
                  inverters:
                    type: array
                    items:
                      type: object
                      properties:
                        isovaPartNumber:
                          type: string
                        partCount:
                          type: integer
      tags:
       - NEW-CAD
      responses:
        200:
          description: CAD record created successfully.
          schema:
            type: object
            properties:
              cadName:
                type: string
              sfId:
                type: string
              sfUrl:
                type: string
          examples:
            cadName: some name
            sfId: a1o4c0000000GGAQA2
            sfUrl: http://some-url-to-nowhere.com
        204:
          description: No project could be found for the given service number.
        500:
          description: Unexpected error. Most likely while communicating with Salesforce.
          schema:
            type: string

所以现在我仍然可以从路径中获取serviceNumber，而其他所有内容都在请求正文中。这里要记住的一件事是你不能使用所有相同的Using Command-Line Functions。例如，我尝试将double用于其中一个属性，Swagger抱怨它无法解析类型double。直到我最终找到Swagger Data Types描述formData参数和body参数之间的区别（我只能有一个参数，因为它描述了整个请求体）之前，我一直很困惑。基本上，您只能使用JSON模式支持的数据类型。

Swagger-UI现在显示单个textarea而不是每个参数的多个输入字段。不是很漂亮，但效果很好。您可以单击右侧的“示例值”框，它会在您的textarea中放置一个预定义的JSON模板，以便您只需填写值。

如果你只是像我一样学习Swagger，我希望这会有所帮助！

如何在swagger参数中描述此JSON对象？

1 个答案: