swagger-api / swagger-api/swagger-ui

Parameter values are too close together (renderedMarkdown margin set to 0 em)

Open
#9,241 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: macOS
  • Browser: chrome
  • Version: 117.0.5938.62
  • Method of installation: npm dist assets
  • Swagger-UI version: 5.2.0 and > 5.2.0
  • Swagger/OpenAPI version: OpenAPI 3.1
Content & configuration

We recently upgraded from OpenAPI 3.0 to 3.1. Upon doing so we found that the additionalProperties: false false was being rendered to additionalProp1. This is a known bug that was fixed in version 5.2.0. We upgraded to the latest version (5.7.2) and found that the spacing in our endpoint parameters had become 'squished'. (see screenshot). I dug around using chrome inspect and found that the margin in the paragraph tag was set to 1em in version 5.2.0 and 0em in versions >= 5.3.0. I dug around some more and found that in version 5.3.0 a fix to descriptions alignment was merged, and may be the cause of our issue.

Margin set to 1 em in 5.2.0
image

Margin set to 0 em in 5.7.2
image

Example Swagger/OpenAPI definition:

{
    "openapi": "3.1.0",
    "info": {
        "title": "DEMO 6.2.0",
        "version": "",
        "description": "DEMO Using swagger-ui-dist 5.2.0"
    },
    "paths": {
        "/api/eligibility/npi/{npi}": {
            "get": {
                "description": "Look up public information for a single provider by NPI.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/accept"
                    }
                ],
                "responses": {
                    "200": {}
                }
            }
        }
    },
    "components": {
        "parameters": {
            "accept": {
                "name": "Accept",
                "in": "header",
                "description": "Request a content type and a specific API version. For example, to request `application/json`\nand version 4 of the API, the header value should be `application/vnd.qpp.cms.gov.v4+json`.\nThe API will return the default version if the Accept header is not\nincluded or if the requested version is not supported.\n",
                "schema": {
                    "type": "string",
                    "enum": [
                        "application/vnd.qpp.cms.gov.v4+json"
                    ],
                    "default": "application/vnd.qpp.cms.gov.v4+json"
                },
                "required": false
            }
        }
    }
}

Swagger-UI configuration options:

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.set('view engine', 'ejs')

app.get('/', (req, res) => {
    res.render('index', {text: "world"});
})

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));



app.listen(3005)
?yourQueryStringConfig
Describe the bug you're encountering
To reproduce...

Steps to reproduce the behavior:

  1. Install express, swagger-ui-dist@5.2.0, swagger-ui-express
  2. Run node app.js
  3. Go to http://localhost:3005/api-docs
  4. Click on GET api/eligibility/npi/{npi}
  5. Scroll down to parameters
  6. See spacing for acceptable values and default values
Expected behavior

I would have expected the parameter space to have not changed between versions. We would prefer the 1em margins in the parameters.

Screenshots

See above

Additional context or thoughts

Based on the comments in #8963 it seems like that ticket was a harmonization of margins across multiple files. So it is unclear if this is a true bug for a bug/feature that we have been used to.

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 spacing difference with the provided app.js setup, comparing swagger-ui-dist 5.2.0 with 5.7.2 around the rendered parameter descriptions. Inspect the description-alignment change referenced in #8963 and verify the affected paragraph margins. Done means parameter values and defaults have the intended spacing without disrupting the alignment fix.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, javascript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.