Come utilizzare i cookie nell'editor Swagger

Question

Desidero documentare e testare un'API, che utilizza l'autenticazione basata su cookie in http://editor.swagger.io/. Per dare un semplice esempio: come scrivere nel seguente YAML, che l'azione/login crea un cookie e il cookie deve essere passato a/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

L'autenticazione dei cookie è supportata in OpenAPI 3.0 ma non in OpenAPI/Swagger 2.0.

In OpenAPI 3.0, cookie di autenticazione è definito come una chiave API che viene inviato 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 

L'operazione di login non è legata a securitySchemes in qualsiasi modo, ma si consiglia di definire l'intestazione di risposta Set-Cookie a fini di documentazione:

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 

detto questo, Swagger Editor e Swagger UI attualmente non supportano l'autenticazione di cookie. Controlla lo OAS 3.0 Support Backlog per gli aggiornamenti.