如何定义将应用于所有路径的全局参数

Question

我想将"account"参数应用于所有路径,没有任何例外.有没有办法用Swagger 2做这个(我不想为每个路径应用"account"参数)？

{
  "swagger": "2.0",
  "info": {
    "version": "1.0",
    "title": "Doc"
  },
  "host": "localhost",
  "schemes": [
    "http"
  ],
  "produces": [
    "application/json"
  ],
  "parameters": {
    "account": {
      "in": "header",
      "name": "X-ACCOUNT",
      "description": "Account id",
      "type": "string",
      "required": true
    }
  },
  "paths": {
    "/account": {
      "get": {
        "summary": "Get account",
        "operationId": "getAccount",
        "responses": {
          "200": {
            "description": "test"
          }
        }
      }
    },
    ..... other paths
  }
}

Answer 1

这取决于它们是什么类型的参数.

以下示例在YAML中(为了便于阅读),但您可以使用http://www.json2yaml.com将它们转换为JSON.

与安全相关的参数:授权标头,API密钥等.

用于身份验证和授权的参数(例如Authorization标头,API密钥,API密钥对等)应定义为安全方案而不是参数.

在您的示例中,X-ACCOUNT看起来像API密钥,因此您可以使用:

swagger: "2.0"
...

securityDefinitions:
  accountId:
    type: apiKey
    in: header
    name: X-ACCOUNT
    description: All requests must include the `X-ACCOUNT` header containing your account ID.

# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
  - accountId: []

工具可以与通用参数不同地处理安全方案参数.例如,Swagger UI不会在操作参数中列出API密钥; 相反,它会显示"授权"按钮,您的用户可以在其中输入其API密钥.

通用参数:偏移量,限制,资源ID等.

OpenAPI 2.0和3.0没有全局参数的概念.存在现有功能请求:
允许在所有端点之间共享响应和参数将
多个参数定义分组以获得更好的可维护性

您可以做的最多是在全局parameters部分(在OpenAPI 2.0中)或components/parameters部分(在OpenAPI 3.0中)中定义这些参数,然后$ref在每个操作中显式定义所有参数.缺点是您需要$ref在每个操作中复制s.

openapi: 3.0.0
...

components:
  securitySchemes:
    accountId:
      type: apiKey
      in: header
      name: X-ACCOUNT
      description: All requests must include the `X-ACCOUNT` header containing your account ID.

# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
  - accountId: []

为了减少代码重复,可以在路径级而不是内部操作中定义适用于路径上所有操作的参数.

swagger: "2.0"
...

paths:
  /users:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...
  /organizations:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...

parameters:
  offset:
    in: query
    name: offset
    type: integer
    minimum: 0
  limit:
    in: query
    name: limit
    type: integer
    minimum: 1
    maximum: 50