如何在Swagger编辑器中使用Cookie

Question

我想记录和测试一个API，它使用http://editor.swagger.io/中的基于Cookie的认证。举一个简单的例子：如何在下面的YAML中写入/ login动作创建一个Cookie并且Cookie必须传递给/ 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验证在OpenAPI 3.0中受支持，但在OpenAPI/Swagger 2.0中不受支持。

在OpenAPI的3.0，cookie认证被定义为发送in: cookie API密钥：

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 

登录操作未链接到securitySchemes以任何方式，但你可能要定义的响应头Set-Cookie出于文档目的：

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 

这就是说，Swagger Editor和Swagger UI目前不支持cookie身份验证。查看OAS 3.0 Support Backlog的更新。