如何描述在 OpenAPI 3 的响应正文中发送的 JWT？答案

【问题标题】：How do I describe a JWT sent in a response body in OpenAPI 3?如何描述在 OpenAPI 3 的响应正文中发送的 JWT？
【发布时间】：2020-05-12 17:47:25
【问题描述】：

根据jwt.io上的JWT introduction，

输出是三个用点分隔的 Base64-URL 字符串，可以在 HTML 和 HTTP 环境中轻松传递。”

我试图弄清楚如何在响应的架构中描述这一点。我被绊倒了，因为在我看来“三个由点分隔的字符串”本身就是一个字符串 - 对吗？

内容部分会是这样吗？

content:
  text/plain:
    schema:
      type: string

In the OpenAPI docs，我在 components/securitySchemes 部分看到了如何描述承载认证，但我认为这与 global/path 操作安全部分有关，而不是服务器发送 JWT 时的登录方法给客户。

【问题讨论】：

标签： jwt swagger openapi

【解决方案1】：

您可以使用text/plain 并添加描述，也可以使用application/jwt media type。或两者兼而有之:-)

responses:
    '200':
      description: a JSON web token (JWT) required to login.
      content:
        application/jwt:
          schema:
            type: string

【讨论】：

【解决方案2】：

你可以试试这样的……（来自https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.8.6）

{
"type": "string",
"format": "application/jwt",
"Schema": {
    "type": "array",
    "minItems": 2,
    "prefixItems": [
        {
            "const": {
                "typ": "JWT",
                "alg": "HS256"
            }
        },
        {
            "type": "object",
            "required": ["iss", "exp"],
            "properties": {
                "iss": {"type": "string"},
                "exp": {"type": "integer"}
            }
        }
    ]
}

}

但它会在 base64url 编码之前显示令牌。

所以我更喜欢写成下面的形式：

json_web_token:
  description: |
    JWT is built in the following format:
      f"base64urlEncoding(header) + '.' + base64urlEncoding(payload) + '.' + base64urlEncoding(signature)"
    header is an object containing -> {"alg": {CHOSEN_ALG}, "typ": "JWT"}
    payload is an object containing the claims (data of jwt)
    signature is an encoded with a PRIVATE_KEY object by our CHOSEN_ALG from the following format: 
      CHOSEN_ALG( PRIVATE_KEY, base64urlEncoding(header) + '.' + base64urlEncoding(payload))
  type: string
  format: application/jwt
  pattern: ^([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_\-\+\/=]+)$
  example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

【讨论】：