How to Use Cookies in Swagger Editor

Question

I would like to document and test an API that uses cookie-based authetication at http://editor.swagger.io/ . To give a simple example: How to write in the following YAML, the / login action creates a Cookie, and must the Cookie be passed / showMySecretStuff?

swagger: '2.0' info: title: Test API version: '1' host: my.test.com schemes: - https basePath: / consumes: - multipart/form-data produces: - application/json paths: /login: post: parameters: - name: username in: formData required: true type: string - name: password in: formData required: true type: string default: secret responses: 200: description: OK /showMySecretStuff: get: responses: 200: description: OK 

Answer 1

Cookie authentication is supported in OpenAPI 3.0, but not in OpenAPI / Swagger 2.0.

In OpenAPI 3.0, cookie authentication is defined as an API key that is sent in: cookie :

 openapi: 3.0.0 ... components: securitySchemes: cookieAuth: type: apiKey in: cookie name: COOKIE-NAME # replace with your cookie name paths: /showMySecretStuff: get: security: - cookieAuth: [] responses: '200': description: OK 

The login operation is not related to securitySchemes any way, but you can define a Set-Cookie response header for documentation purposes:

 paths: /login: post: requestBody: ... responses: '200': description: OK headers: Set-Cookie: description: > Contains the session cookie named `COOKIE-NAME`. Pass this cookie back in subsequent requests. schema: type: string 

However, the Swagger editor and Swagger user interface do not currently support cookie authentication. Check out the OAS 3.0 Support Backlog for updates.