如何定义将应用于所有路径的全局参数? [英] How to define global parameters that will apply to all paths?

问题描述

我想使account参数适用于所有路径，没有任何例外. Swagger 2有什么方法可以做到这一点吗?我不想为每个路径应用account参数.

I want to make the account parameter to be applied to all paths, without any exceptions. Is there any way to do this with Swagger 2? I don't want apply the account parameter for every path.

{
  "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
  }
}

推荐答案

这取决于它们是哪种参数.

It depends on what kind of parameters they are.

下面的示例在YAML中(出于可读性考虑)，但是您可以使用 http://www.json2yaml.com 将其转换为JSON.

The examples below are in YAML (for readability), but you can use http://www.json2yaml.com to convert them to JSON.

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

Parameters used for authentication and authorization, such as the Authorization header, API key, pair of API keys, etc. should be defined as security schemes rather than parameters.

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

In your example, the X-ACCOUNT looks like an API key, so you can use:

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: []

或在OpenAPI 3.0中:

or in OpenAPI 3.0:

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 UI不会在操作参数中列出API密钥.而是显示授权"按钮，您的用户可以在其中输入其API密钥.

Tools may handle security schemes parameters differently than generic parameters. For example, Swagger UI won't list API keys among operation parameters; instead, it will display the "Authorize" button where your users can enter their API key.

OpenAPI 2.0和3.0没有全局参数的概念.现有的功能请求:
允许在所有端点之间共享响应和参数
对多个参数定义进行分组以提高可维护性

OpenAPI 2.0 and 3.0 do not have a concept of global parameters. There are existing feature requests:
Allow for responses and parameters shared across all endpoints
Group multiple parameter definitions for better maintainability

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

The most you can do is define these parameters in the global parameters section (in OpenAPI 2.0) or the components/parameters section (in OpenAPI 3.0) and then $ref all parameters explicitly in each operation. The drawback is that you need to duplicate the $refs in each operation.

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

要在某种程度上减少代码重复，可以在路径级别而不是内部操作中定义适用于路径上所有操作的参数.

To reduce code duplication somewhat, parameters that apply to all operations on a path can be defined on the path level rather than inside operations.

paths:
  /foo:
    # These parameters apply to both GET and POST
    parameters:
      - $ref: '#/parameters/some_param'
      - $ref: '#/parameters/another_param'

    get:
      ...
    post:
      ...

这篇关于如何定义将应用于所有路径的全局参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！