OpenAPI带CSRF Token的两步认证流程优化方案咨询

针对你的两步认证API（先GET /获取会话Cookie和CSRF Token，再POST /login完成登录）的OpenAPI规范编写需求，这里有几个更优雅的优化方向和实现方案，同时能让生成的客户端代码更简洁易用。

当前实现 #

OpenAPI规范 #

components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: session

  parameters:
    CSRFTokenHeader:
      name: X-CSRF-TOKEN
      in: header
      required: false
      schema:
        type: string

  schemas:
    LoginRequest:
      type: object
      required:
        - username
        - password
        - _csrf
      properties:
        username:
          type: string
        password:
          type: string
        _csrf:
          type: string
          description: CSRF token obtained from initial request

paths:
  /:
    get:
      tags:
        - session
      operationId: getInitialSession

  /login:
    post:
      tags:
        - session
      operationId: loginUser
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoginRequest'

生成的Python客户端代码 #

session_api = my_api.SessionApi(api_client=client)
init_result = session_api.get_initial_session_with_http_info()
assert init_result.headers
client.cookie = init_result.headers["Set-Cookie"]
csrf_token = init_result.headers["X-CSRF-TOKEN"]
session_api.login_user_with_http_info(
    username=os.environ.get("MY_API_USERNAME"),
    password=os.environ["MY_API_PASSWORD"],
    csrf=csrf_token,
)

优化后的OpenAPI规范 #

主要优化点：

• 明确GET /的响应头定义，让生成的客户端自动识别Cookie和CSRF Token
• 通过links字段关联两步操作，清晰展示流程依赖
• 补充操作的summary和description，提升规范可读性

openapi: 3.0.3
info:
  title: 两步认证API
  version: 1.0.0

components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: 会话Cookie，通过`GET /`接口获取

  schemas:
    LoginRequest:
      type: object
      required:
        - username
        - password
        - _csrf
      properties:
        username:
          type: string
        password:
          type: string
        _csrf:
          type: string
          description: CSRF Token，从`GET /`的响应头`X-CSRF-TOKEN`中获取

paths:
  /:
    get:
      tags:
        - 会话管理
      operationId: getInitialSession
      summary: 获取会话Cookie与CSRF Token
      responses:
        '200':
          description: 成功返回会话基础信息
          headers:
            Set-Cookie:
              description: 用于后续请求的会话Cookie
              schema:
                type: string
            X-CSRF-TOKEN:
              description: 登录请求所需的CSRF Token
              schema:
                type: string
          links:
            loginUser:
              operationId: loginUser
              description: 使用当前接口获取的Cookie和Token执行登录
              parameters:
                _csrf: '$response.header.X-CSRF-TOKEN'

  /login:
    post:
      tags:
        - 会话管理
      operationId: loginUser
      summary: 用户登录
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: 登录成功
        '401':
          description: 用户名/密码错误或认证信息无效

优化后的生成客户端代码 #

补充响应定义和操作关联后，生成的Python客户端会自动处理Cookie的保存（大部分OpenAPI生成器会默认维护Cookie池），无需手动设置client.cookie，代码更简洁：

session_api = my_api.SessionApi(api_client=client)
# 调用后客户端自动保存会话Cookie
init_response = session_api.get_initial_session_with_http_info()
csrf_token = init_response.headers.get("X-CSRF-TOKEN")

# 客户端自动携带已保存的会话Cookie
session_api.login_user(
    username=os.environ.get("MY_API_USERNAME"),
    password=os.environ["MY_API_PASSWORD"],
    _csrf=csrf_token
)

额外建议 #

• 如果API的CSRF Token是通过响应体返回而非响应头，可在GET /的响应中添加content字段定义响应体schema，让客户端直接解析Token
• 若API支持将CSRF Token放在请求头X-CSRF-TOKEN中传递而非表单参数，可调整login接口的参数定义，让客户端更符合常规CSRF处理流程

内容的提问来源于stack exchange，提问作者Manuel