Modeling form-data API request using swagger 2.0

user_10234240 0
Viewed 211

I have the following API request: enter image description here

I have a problem of how to model the array part where there is for example skills[0][name]:

so OK, it is array type with items, but how do you model the [name] part in swagger? how would it look like? I've tried the following:

- in: formData
        name: skills
        type: array
        items:
            type: string

but how do you model the [id] part for example?

------------------------------EDIT----------------------------

As suggested I implemented the following:

parameters:
    - $ref: '#/parameters/xAccessTokenHeader'
    - in: formData
      name: name
      type: string
      required: true
    - in: formData
      name: status
      type: integer
    - in: formData
      name: level
      type: integer
      required: true
    - in: formData
      name: classification
      type: integer
      required: true
    - in: formData
      name: description
      type: string
      required: true
    - in: formData
      name: icon
      type: string
      required: true
    - in: formData
      name: syllabi
      type: array
      items:
        type: integer
    - in: formData
      name: institutions
      type: array
      items:
        type: integer  
    - in: formData
      name: skills[0][name]
      type: string
    - in: formData
      name: skills[0][id]
      type: string
    - in: formData
      name: skills[0][selected]
      type: boolean
    - in: formData
      name: skills[0][type]
      type: string
    - in: formData
      name: skills[1][name]
      type: string
    - in: formData
      name: skills[1][id]
      type: string
    - in: formData
      name: skills[1][selected]
      type: boolean
    - in: formData
      name: skills[1][type]
      type: string
    - in: formData
      name: lessons
      type: array
      items: 
        type: string
    - in: formData
      name: status_mode
      type: integer
  responses:
    "201":
      description: "Created"

but when I sent the request I got the following error:

{"message":"The given data was invalid.","errors":{"syllabi":["The syllabi must be an array."],"lessons":["The lessons must be an array."]}}

and this is my java code that wrap code generation from swagger:

public void createNewModule(String moduleName, Status status, String desc, String icon) throws ApiException {
        List<String> lessonLst = Arrays.asList("790f67a7-47de-4c86-aacb-b64ad10e8c76");
        List<Integer>syllabiLst = Arrays.asList(0,1,2);
        List<Integer>institutionsLst = Arrays.asList(0,1);

        practiceArenaApi.createNewModule(token, moduleName, 4, 2, desc, icon, status.apiStatus, syllabiLst, institutionsLst,
                "Web-scraping in Python", "1",  true, "prerequisite",
                "SMTP", "5", true, "achieved", lessonLst, 1);

    }

indicating that the post request was illegal.

For the following form-data parameters: enter image description here

swagger api yaml
1 Answers

In OpenAPI 2.0, form fields with [smth] in the name need to be defined as individual parameters:

parameters:
  - in: formData
    name: skills[0][name]
    type: string
  - in: formData
    name: skills[0][id]
    type: string
  - in: formData
    name: skills[0][selected]
    type: boolean
  - in: formData
    name: skills[1][name]
    type: string
  # etc.

This means you can't really describe form data containing arbitrary-length arrays of objects, as you need to define all possible indexes (0, 1, 2, etc.) in advance as part of individual parameter names.

If you are designing a new API rather than documenting an existing one, consider using a JSON body instead of form data.

user_1131160
Related