swagger-api / swagger-api/swagger-codegen-generators
Support for both required and optional form parameters
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-urlencodedrequest body is required - The form must have an
idfield - The form can have a
namefield 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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