Cách sử dụng Cookie trong trình chỉnh sửa Swagger

Question

Tôi muốn tài liệu và kiểm tra API, sử dụng tính năng xác thực dựa trên cookie trong http://editor.swagger.io/. Để đưa ra một ví dụ đơn giản: Làm thế nào để viết trong YAML sau, hành động/login đó tạo ra một Cookie và Cookie phải được chuyển đến/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

Xác thực cookie được hỗ trợ trong OpenAPI 3.0 nhưng không được hỗ trợ trong OpenAPI/Swagger 2.0.

Trong OpenAPI 3.0, xác thực cookie được định nghĩa là một khóa API được gửi 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 

Các hoạt động đăng nhập không liên kết với securitySchemes trong bất kỳ cách nào, nhưng bạn có thể muốn xác định các tiêu đề phản ứng Set-Cookie cho mục đích tài liệu:

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 

Điều đó nói rằng, Swagger Editor và Swagger UI hiện không hỗ trợ xác thực cookie. Hãy xem OAS 3.0 Support Backlog để biết các cập nhật.