Troubleshooting Common Issues in SwaggerAPI SwaggerUI

Project Description

Swagger UI is a user interface that allows you to visualize and interact with the API endpoints and resources defined in a Swagger definition. It is a web-based tool that can be used to create and consume API documentation.

With Swagger UI, you can view the API endpoints and their corresponding documentation in a web browser. You can also send API requests and view the responses directly from the Swagger UI interface. This can be helpful for testing and debugging APIs, as well as for learning how to use the API.

Swagger UI is typically used in conjunction with the Swagger Core library, which is a Java library for creating and using Swagger definitions. You can use the Swagger Core library to create a Swagger definition for your API, and then use Swagger UI to visualize and interact with the API endpoints and resources defined in the Swagger definition.

Troubleshooting SwaggerAPI SwaggerUI with the Lightrun Developer Observability Platform

Getting a sense of what’s actually happening inside a live application is a frustrating experience, one that relies mostly on querying and observing whatever logs were written during development.
Lightrun is a Developer Observability Platform, allowing developers to add telemetry to live applications in real-time, on-demand, and right from the IDE.

• Instantly add logs to, set metrics in, and take snapshots of live applications
• Insights delivered straight to your IDE or CLI
• Works where you do: dev, QA, staging, CI/CD, and production

Start for free today

The following issues are the most popular issues regarding this project:

Multiple responses using oneOf attribute do not appear in UI

While utilizing the oneOf feature to target a specific type within components or schema can appear beneficial, it turns out this approach is unfortunately ineffective in solving the current problem.

components:
  responses:
    ...
    ServerWriteError:
      description: Write Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerWriteErrorResponse'

  schemas:
    ...
    ServerWriteErrorResponse:
      oneOf:
        - $ref: '#/components/schemas/PartialWriteError'
        - $ref: '#/components/schemas/BaseError'

To circumvent this issue, one could declare “type: object” alongside the presence of oneOf. This strategy offers flexibility in accommodating different incoming values while still enforcing data integrity within your designs.

components:
  responses:
    ...
    ServerWriteError:
      description: Write Failed
      content:
        application/json:
          schema:
            oneOf:
            $ref: '#/components/schemas/ServerWriteErrorResponse'

  schemas:
    ...
    ServerWriteErrorResponse:
      type: object     # Workaround-ish
      oneOf:
        - $ref: '#/components/schemas/PartialWriteError'
        - $ref: '#/components/schemas/BaseError'

In the component of the schema referred to, a new and enlightening insight will be provided.

components:
 responses:
    ...
    ServerWriteError:
      description: Write Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerWriteErrorResponse'

  schemas:
    ...
    ServerWriteErrorResponse:
      type: object
      oneOf:
        - $ref: '#/components/schemas/PartialWriteError'
        - $ref: '#/components/schemas/BaseError'

Despite the less-than-ideal workarounds, consumers can still gain much-needed clarity – by being able to view relevant models accompanied by an empty object in the returned example.

Unrecognized response type – application/pdf displayed incorrectly in the response body

After some trial and error, a successful resolution was ultimately achieved by the addition of headers to the response.

res.setHeader('Content-Type', 'application/pdf');
res.setHeader('Content-Disposition', 'attachment; filename=labels.pdf');

Path parameter issues: “Required field is not provided” or interpolates to a ‘,’

Conflicting versions of React can lead to issues if a project is using react v16, but its dependency on react-debounce-input has "react": "^15.3.0 || ^16.0.0." This issue arises when setState’s callback in the latter does not function properly causing onChange prop failure; hence swagger-UI works as it allows fixing of dependencies into one file and forces the use of React version 15 for compatibility purposes only.

For example, if you use “react 16” in your project, then your node_modules will look like this:

-node_modules
└ react(16)
└ react-debounce-input(3.2.2) <- will use project react version
└ swagger-ui
     └ node_modules
             └ react(15)

To resolve this issue, you must ensure that an older version of react-debounce-input is installed within the swagger UI node_modules. This can be done by forcibly requiring its installation in order to continue your work uninterrupted.

npm i --save-dev react-debounce-input@3.1.0

-node_modules
└ react(16)
└ react-debounce-input(3.1.0)
└ swagger-ui
    └ node_modules
         └ react(15)
              └ react-debounce-input(3.2.2) <- will use the same react version as swagger-ui

To achieve the desired outcome, a shift in dependency has to be made from react-debounce-input to “react”: “^15.3.0”. Unfortunately, swagger-UI-react does not provide any assistance here as it requires version 16; however, due to that implementation various warnings are thrown and many deprecated components emerge creating an unpleasant user experience.

More issues from SwaggerAPI repos

Troubleshooting swagger-editor | Troubleshooting swagger-core | Troubleshooting swagger-parser