swagger-api / swagger-api/swagger-ui

Allow free-form Cookie header to be set in the Authorise modal

Open
#9,710 1 comment 1 reaction 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:

openapi: 3.0.1
info:
 title: Some Example Service
 version: "1.0"
servers:
- url: http://localhost:8080
 description: Generated server url
security:
- Cookie: []
paths:
 /something/create:
   post:
     operationId: createSomething
     parameters:
       - name: client-id
         in: header
         required: false
         schema:
           type: string
     responses:
       "201":
         description: Created
components:
 securitySchemes:
   Cookie:
     type: apiKey
     description: Authentication Cookies
     name: Cookie
     in: header

Swagger-UI configuration options:

SwaggerUI({
  persistAuthorization: true
})
Is your feature request related to a problem?

Clients are not able to set free-form cookies in the browser rendering the try it out function useless for a number of our APIs.

Describe the solution you'd like

When a header authorization named Cookie is configured in security schema and the persist authorization option is set to true, and the authorize button is clicked, the free-form cookie values provided in the authorization modal should be set on the browser, thus sent with any request to the same origin. The path for these cookies should be set to "/" to ensure the cookies are attached to every same origin request (it appears as though this feature sets these to the Swagger UI path based on my limited testing).

cookie

Describe alternatives you've considered

Alternative is to let the request fail in the UI and copy the curl request to be performed on the users terminal or provide some javascript helper to set the cookies through the browser console independent of Swagger UI. Both of these are cumbersome and put a dent in the usability/benefits of the Swagger UI.

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 at the Authorize modal and the SwaggerUI configuration using persistAuthorization: true, then trace how a Cookie security scheme is handled when authorization is saved. Done means free-form Cookie values entered for the Cookie header are set as browser cookies with path "/" and are sent on same-origin Try It Out requests.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, authentication, frontend, security
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.