cookies - 如何在 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 key 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以任何方式，但您可能想要定义响应头 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和 this issue更新。

SwaggerHub 支持 Cookie 身份验证尽管。 (披露:SwaggerHub 是我工作的公司的产品。)