swagger-api / swagger-api/swagger-codegen

[typescript-angular] (swagger-codegen 3.x) Constrained query parameter values in YAML are not constrained in client

Open
#10,148 0 comments 1 reaction 0 assignees View on GitHub

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:

  • CreatedOn
  • CreatedBy

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).

  1. Copy the RestApi-constrained-sort.yml contents into the online Swagger Editor
  2. Click on Generate Client drop-down menu.
  3. Select typescript-angular.
  4. Open the downloaded generated client content (zip file):
    1. Open the api folder

    2. Inspect the calcSessions.service.ts file.
      ℹ️ I copied the contents of the calcSessions.service.ts file into a gist, for easier inspection.

    3. Notice on Lines 68-71 the sort parameter is allowed to be any string (Array<string>) instead of constrained to createdOn and createdBy (Array<'createdOn' | 'createdBy'>)

Related issues/PRs
I was not able to find a related issue/PR.

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.