我该如何用昂扬的参数描述这个JSON对象？

Question

I've looked at a few other related questions and I still can't seem to find what I'm looking for. This is an example JSON payload being sent to an API I'm writing:

{
    "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
        }]
    }
}

Describing all the beginning parameters was easy.

/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

And yields the expected result in Swagger-UI:

But now I'm struggling with the last parts of the example JSON payload above. I'm unsure how to express the energyProduction key which is an object with a key for each month of the year. I'm also unsure how to describe roofSections which is an array of objects and systemConfiguration which is an object with a property inverters whose value is an array of objects.

I'm going over the swagger documentation quite a bit but I'm still pretty confused and hoping maybe someone here can explain things a little better to me.

Answer 1

I figured it out. Turns out formData is not what I should have been using for my parameters. Instead I needed to use body and define the structure of the JSON that would populate the body. Here is the completed design file using a body parameter with an object schema and describes all the nested objects and arrays as well.

 /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

So now I can still get the serviceNumber from the path while everything else comes in the request body. One thing to keep in mind here is that you cannot use all the same Swagger Data Types . For example I tried to use double for one of the properties and Swagger complained that it couldn't parse type double . I was very confused until I finally found the section of the docs describing the difference between formData parameters and a body parameter (of which you can only have one, because it describes the entire request body). Basically you can only use data types that are supported by the JSON schema.

Swagger-UI now shows a single textarea instead of multiple input fields for each parameter. Not as pretty but it works great. You can click the "Example Value" box on the right and it places a predefined JSON template in the textarea for you so you can just fill in the values.

If you are just learning Swagger like I am I hope this helps!