swagger-api / swagger-api/swagger-ui
Allow free-form Cookie header to be set in the Authorise modal
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 sets these to the Swagger UI path based on my limited testing).
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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