Как использовать Cookies в Редакторе Swagger

Я хотел бы документировать и тестировать API, который использует аутентификацию на основе файлов Cookie в http://editor.swagger.io/. Чтобы дать простой пример: как написать в следующем 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
6
cookies swagger-editor

1 ответов

аутентификация Cookie поддерживается в OpenAPI 3.0, но не в 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 в любом случае, но вы можете определить заголовок ответ 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 и этот вопрос для обновления.

файл cookie проверки подлинности, поддерживаемые в SwaggerHub хотя. (раскрытие: SwaggerHub является продуктом компании я работаю.)

0