swagger-api / swagger-api/swagger-ui

Models names containing / and ~ are displayed with ~1 and ~0 instead

Open
#4,161 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Q A
Bug or feature request? Bug
Which Swagger/OpenAPI version? 2.0
Which Swagger-UI version? 3.9.1
How did you install Swagger-UI? http://editor.swagger.io
Which browser & version? Chrome
Which operating system? Windows 7

This is a minor display issue related to #4152.

/ and ~ are special characters in JSON Pointers, so when they need to be used literally (as part of a node name) they are encoded as ~1 and ~0, as per https://tools.ietf.org/html/rfc6901#section-3.

# Referencing a model named "foo/bar"
$ref: '#/definitions/foo~1bar'

definitions:
  foo/bar:
   ...

However, in places where the model is referenced, the UI displays the model name incorrectly - still encoded using ~1 and ~0 instead of the actual name with / ~.

Demonstration API definition
swagger: '2.0'
info:
  version: 0.0.0
  title: test
paths:
  /foo:
    post:
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/x~1Foo'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/x~1Foo'
        404:
          description: OK
          schema:
            $ref: '#/definitions/x~0Bar'
definitions:
  x/Foo:
    type: object
    properties:
      bar:
        $ref: '#/definitions/x~0Bar'
  x~Bar:
    type: object
Expected Behavior

Model names everywhere are displayed as x/Foo and x~Bar.

Current Behavior

In places where the models are $referenced, the model names are displayed as x~1Foo and x~0Bar instead of x/Foo and x~Bar.

ui-v3

Possible Solution

N/a

Context

Model names containing / and ~ are displayed correctly in Editor v2:
editor-v2

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

Start by reproducing the issue with the demonstration Swagger 2.0 API definition in this report, focusing on the Swagger UI locations that render referenced model names. Done means references to models named x/Foo and xBar display those literal names rather than x1Foo and x~0Bar.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.