How to define global parameters that will apply to all paths?

问题

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

回答1:

It depends on what kind of parameters they are.

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

Security-related parameters: Authorization header, API keys, etc.

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.

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

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

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.

Generic parameters: offset, limit, resource IDs, etc.

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

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:
      ...

来源：https://stackoverflow.com/questions/39791491/how-to-define-global-parameters-that-will-apply-to-all-paths

标签

swagger-2.0

openapi