swagger-api / swagger-api/swagger-ui

How to use OpenAPI feature LINKS in Swagger-UI? It does not seem to work properly

Open
#7,533 3 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: rendering specification: 3.x
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
  • Swagger-UI version: v3.52.3
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

Swagger/OpenAPI definition:

openapi: "3.0.2"

info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: "xxxxx"

paths:
  /hello/user:
    post:
      operationId: createUser
      summary: create a user
      description: create new user
      requestBody:
        description: new user
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string

          # -----------------------------------------------------
          # Links
          # -----------------------------------------------------
          links:
            GetUserByUserId:   # <---- arbitrary name for the link
              operationId: getUser
              # or
              # operationRef: '#/paths/~1users~1{userId}/get'
              parameters:
                uid: '$request.body#/uid'
              description: >
                The `uid` value returned in the response can be used as
                the `uid` parameter in `GET /hello/user`.
          # -----------------------------------------------------


    get:
      operationId: getUser
      summary: Return a user
      description: Optional extended description in CommonMark or HTML.
      parameters:
        - in: query
          name: uid
          schema:
            type: integer
      responses:
        '200':    # status code
          description: return a user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: Object
      required:
      - uid
      properties:
        name:
          type: string
        uid:
          type: integer
      example:
        uid: 1
        name: 'juno'
Screenshots
Screen Shot 2021-10-02 at 5 27 06 PM Screen Shot 2021-10-02 at 5 22 06 PM
How can we help?

According to the documentation on Links feature, I would expect there is clickable links in the POST response to link to the GET request here. But I don't see any clickable links there. Could you please check if anything wrong? How does the Links feature work? Many thanks!

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 with the supplied OpenAPI 3.0 definition and Swagger UI v3.52.3, then compare the documented Links feature with the POST response shown in the screenshots. Determine whether the expected clickable link should appear and document or reproduce the behavior using the provided definition.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.