swagger-api / swagger-api/swagger-client

Swagger spec is not normalized if structure is hidden behind a reference

Open
#1,396 3 comments 0 reactions 1 assignee View on GitHub

@char0n is already working on this.

Since Jan 3, 2023.

cat: resolver type: bug
Dominant language
JavaScript
Stars
2.7k
Forks
765
Avg merge
1d 1h
Merged PRs (30d)
6

Description

I tracked down a regression in swagger-ui to an interaction between swagger normalization and subtree resolution introduced in https://github.com/swagger-api/swagger-js/pull/1274.

With that change, normalization happens only before subtree resolution, and this breaks in cases where the structure of the references hides the structure of the swagger file from normalization.

I boiled it down to this this test https://github.com/swagger-api/swagger-js/compare/master...biochimia:regression/normalize-before-resolution

Q&A (please complete the following information)
  • OS: [e.g. macOS] macOS
  • Environment: [e.g. Chrome 59, Node.js v10.0.0] Node.js v10.12.0
  • Method of installation: [e.g. npm, unpkg] npm
  • Swagger-Client version: [e.g. 3.8.0] >3.6.0, <=3.8.21
  • Swagger/OpenAPI version: [e.g. Swagger 2.0, OpenAPI 3.0] OpenAPI 3.0
Content & configuration

Test case: https://github.com/swagger-api/swagger-js/compare/master...biochimia:regression/normalize-before-resolution

Swagger/OpenAPI definition:

paths.yaml:
  root:
    parameters:
      - $ref: '#/parameters.yaml/accept-header'
    get:
      parameters:
        - $ref: '#/parameters.yaml/name'
        - $ref: '#/parameters.yaml/status'
parameters.yaml:
  accept-header:
    name: accept
    in: header
    description: content-type for response
    required: true
    type: string
  name:
    name: name
    in: formData
    description: name of the pet
    required: false
    type: string
  status:
    name: status
    in: formData
    description: status of the pet
    required: false
    type: string
paths:
  /:
    $ref: '#/paths.yaml/root'

Swagger-Client usage:

SwaggerClient({
  // your config options here
})
Describe the bug you're encountering

Because normalizeSwagger() doesn't get to see the structure of the path object before resolution, if doesn't copy path parameters into individual methods. Later when the subtrees are resolved normalization is already disabled and is not performed.

To reproduce...

Steps to reproduce the behavior:

  1. ...
Expected behavior
Screenshots
Additional context or thoughts

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.