swagger-api / swagger-api/swagger-ui

Swagger UI when working with Swagger 2.0 document wrongly interprets 'required' attribute on schema

Open
#7,107 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • OS: Windows
  • Browser: Chrome, Firefox
  • Version: Chrome:89, Firefox:86
  • Method of installation: Bundled with Swashbuckle.AspNetCore
  • Swagger-UI version: 3.42.0
  • Swagger/OpenAPI version: Swagger 2.0
Content & configuration

Example Swagger/OpenAPI definition:

swagger: '2.0'
info:
  title: Sample API
  description: 'A sample application with Swagger, Swashbuckle, and API versioning.'
  version: '1.0'
paths:
  /api/v1/create:
    post:
      tags:
        - Api
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/TestRequest'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/TestResponse'
definitions:
  TestRequest:
    type: object
    properties:
      test:
        type: string
      testRequestData:
        $ref: '#/definitions/TestRequestData'
  TestRequestData:
    required:
      - testRequestDataItem
    type: object
    properties:
      testRequestDataItem:
        type: string
  TestResponse:
    type: object
    properties:
      status:
        type: string

Swagger-UI configuration options:

SwaggerUI({
  "urls": [
    {
      "url": "/swagger/v1/swagger.json",
      "name": "V1"
    }
  ],
  "deepLinking": false,
  "displayOperationId": false,
  "defaultModelsExpandDepth": 1,
  "defaultModelExpandDepth": 1,
  "defaultModelRendering": "example",
  "displayRequestDuration": false,
  "docExpansion": "list",
  "showExtensions": false,
  "showCommonExtensions": false,
  "supportedSubmitMethods": [ "get", "put", "post", "delete", "options", "head", "patch", "trace" ]
})
N/A
Describe the bug you're encountering

Swagger UI when working with Swagger 2.0 document wrongly interprets 'required' attribute on schema. It wrongly applies it to parent instead of child or misbehaves at all.

To reproduce...

Steps to reproduce the behavior:

  1. Use swagger ui to open spec document
  2. use 'POST ​/api​/v1​/create' to test
  3. Below request does not work when clicking 'Execute', no output on console, no any other user visible message

{
"test": "string",
}

Note: testRequestData is not set as required in swagger 2.0 spec yet swagger ui client code for Swagger 2.0 document rejects request

  1. Surprisingly below request works

Swagger UI submits data to server, yet 'testRequestData/testRequestDataItem' is not present

{
"test": "string",
"testRequestData": {
}
}

Expected behaviour

API requests on client side are validated as per Swagger 2.0 specification or not validated at all.
NB: For OAS 3.0 document it looks 'required' is not checked, swagger ui POSTs data regardless presence of 'required' elements.

Screenshots

N/A

Additional context or thoughts

N/A

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

No source file, test, or entry point is named. Reproduce the Swagger 2.0 example in Swagger UI 3.42.0, then trace the client-side validation of nested schema properties; done means requests follow the specification's required fields or are not rejected incorrectly.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.