swagger-api / swagger-api/swagger-ui

Improve and fix code rendering and parsing of parameter allowed values and defaults

Open
#10,949 0 comments 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

Content & configuration

Swagger/OpenAPI definition:

api.yaml

Using latest https://github.com/swagger-api/swagger-ui/releases/tag/v5.32.8

Swagger-UI configuration options:

           window.ui = SwaggerUIBundle({
               url: "${openapi_json_path}",
               dom_id: "#swagger-ui",
               deepLinking: true,
               defaultModelsExpandDepth: 1,
               defaultModelExpandDepth: 1,
               docExpansion: "list",
               validatorUrl: false,
               presets: [
                   SwaggerUIBundle.presets.apis,
               ],
               plugins: [
                   SwaggerUIBundle.plugins.DownloadUrl
               ],
               tagsSorter: "alpha",
               apisSorter : "alpha",
               operationsSorter: "alpha",
           });
Is your feature request related to a problem?

As shown below, the */* is incorrectly converted into <em>/</em> instead of the expected */*.
Furthermore, the rendering is not that great (code style like paths would be better).

Image

Using the "Try it out" view, the value is correctly */*, so it seems an issue just on the preview of values.

Image
Describe the solution you'd like

It should render similar to what redoc does, which makes interpretation clearer.
It should also ensure proper wraping of the values.

Image
Describe alternatives you've considered

Custom CSS. However, that still doesn't fix the invalid */* value.

The CSS does not allow much flexibility either given how the HTML is generated with broad classes (ie: the enum is pre-concatenated a one comma-separated list of values).

Image

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

Reproduce the issue with the provided api.yaml and SwaggerUIBundle configuration, comparing the parameter allowed-value preview with the correctly rendered Try it out value. Trace the generated preview for the */* value and the comma-separated enum display, then verify that values remain valid, readable, and wrapped as intended.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, javascript, openapi
Domain
api, documentation, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.