swagger-api / swagger-api/swagger-codegen
[typescript-angular] (swagger-codegen 3.x) Constrained query parameter values in YAML are not constrained in client
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
When defining a query parameter, sometimes we also define the possible values that that parameter can be.
Using an endpoint that supports sorting on a GET operation as an example:
A client can get all Notes for a session.
A Note has two properties that we allow to be used for sorting:
CreatedOnCreatedBy
In Swagger 2, this was defined as such:
- name: "sort"
in: "query"
description: "property that will be used for sorting; prefix with '-' to reverse"
required: false
type: "array"
uniqueItems: true
collectionFormat: multi
items:
type: "string"
enum: ["createdOn", "createdBy"]
In this manner, a client can request sorting only on those 2 properties and not, e.g., a third property called "content".
The generated client code (from https://generator.swagger.io/) looked like this:
Note the sort param is "constrained" to those 2 properties -- Array<'createdOn' | 'createdBy'>
public getSessionNotes(sessionId: string, cursor?: string, limit?: number, sort?: Array<'createdOn' | 'createdBy'>, observe?: 'body', reportProgress?: boolean): Observable<Array<Note>>;
In OAS3 YAML (using the online Swagger editor to convert from Swagger 2 to OAS 3), this same parameter is defined as:
- name: sort
in: query
description: property that will be used for sorting; prefix with '-' to reverse
style: form
explode: true
schema:
uniqueItems: true
type: array
items:
type: string
enum:
- createdOn
- createdBy
The generated client code (using 3rd generation online Swagger generator) no longer constrains the value, allowing any value to be passed:
Note that sort is now Array<string>
public getSessionNotes(sessionId: string, cursor?: string, limit?: number, sort?: Array<string>, observe?: 'body', reportProgress?: boolean): Observable<Array<Note>>;
Swagger-codegen version
3.0.18 (using the "3rd Gen" online generator (https://generator3.swagger.io/index.html))
This worked fine using Swagger 2 (https://generator.swagger.io/)
Swagger declaration file content or url
RestApi-constrained-sort.yml
Options used for generation
(note: not including the spec object, for simplicity; see subsequent note in Repro Steps)
{
"lang": "typescript-angular",
"specURL": "string",
"type": "CLIENT",
"codegenVersion": "V3",
"options": {
"additionalProperties": {
"sortParamsByRequiredFlag": false,
"ensureUniqueParams": false,
"supportsES6": true,
"npmName": "test-client",
"npmVersion": "0.0.1",
"providedInRoot": true,
"ngVersion": "7.2.8"
}
}
}
Steps to reproduce
❗️ For simplicity sake, I'm listing the easiest way to reproduce the issue. This is not the process we use "in real life" (but the results are the same).
- Copy the RestApi-constrained-sort.yml contents into the online Swagger Editor
- Click on
Generate Clientdrop-down menu. - Select
typescript-angular. - Open the downloaded generated client content (zip file):
-
Open the
apifolder -
Inspect the
calcSessions.service.tsfile.
ℹ️ I copied the contents of the calcSessions.service.ts file into a gist, for easier inspection. -
Notice on Lines 68-71 the
sortparameter is allowed to be any string (Array<string>) instead of constrained tocreatedOnandcreatedBy(Array<'createdOn' | 'createdBy'>)
-
Related issues/PRs
I was not able to find a related issue/PR.
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 RestApi-constrained-sort.yml definition and inspect the generated api/calcsSessions.service.ts output, especially lines 68-71. Compare the OAS3 enum handling with the Swagger 2 output, then reproduce with the typescript-angular generator and verify that sort is emitted as Array<'createdOn' | 'createdBy'> rather than Array.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- angular, typescript
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100