如何在 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

OpenAPI 3.0 支持 Cookie 身份验证，但 OpenAPI/Swagger 2.0 不支持。

在 OpenAPI 3.0 中，cookie 身份验证定义为发送的 API 密钥 in: cookie:

openapi: 3.0.1
...

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，但出于文档目的，您可能需要定义响应 header 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 and this issue 更新。

不过 SwaggerHub 支持 Cookie 身份验证。 （披露：SwaggerHub 是我工作的公司的产品。）

如何在 Swagger 编辑器中使用 Cookie

How to use Cookies in Swagger editor

cookies

swagger-editor