swagger-api / swagger-api/swagger-codegen-generators

Support for both required and optional form parameters

Open
#374 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
299
Forks
439
PR merge metrics
No merged PRs in 30d

Description

The current code that gathers the form parameters ignores the per-field required flag on them and overrides them based on the whole request body's required flag. I can see that this is intended as there are even tests for this behavior.

This is a serious limitation and prevents us describing some APIs that were possible with Swagger2 + codegen.

Let's see a modified version of the example used in the repo, requiredFormParamTest:

openapi: 3.0.0
info:
  title: Test Api
  version: '3.0.0'

paths:
  /test_required:
    post:
      summary: Operation with form body that is required
      operationId: get_with_required_body
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        "200":
          description: Success

  /test_optional:
    post:
      summary: Operation with form body that is optional
      operationId: get_with_optional_body
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        "200":
          description: Success

components:
  schemas:
    Category:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

The difference is that I explicitly marked id as required.

With this, get_with_required_body should mean that:

  • Having a application/x-www-form-urlencoded request body is required
  • The form must have an id field
  • The form can have a name field but it is optional

The generated code can accept requests with one of two form fields, and the request handler can get an optional value for the name and a non-optional one for the id.

In the get_with_optional_body the whole request body is optional, so the request handler would have to get all the parameters as optionals.

With the current implementation all the fields are either required or optional.
I'm creating a pull request with a proposed implementation that reflects my interpretation described above.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the repository's requiredFormParamTest example and the tests covering how form parameters inherit the request body's required flag. Trace the form-parameter gathering entry point and update the behavior so request-body optionality and per-field requiredness are represented separately; done means requiredFormParamTest accepts the required id, optional name, and optional whole body as described.

Written by the indexing model from the issue text.

Assessment

Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.