How to define global parameters in OpenAPI?

by

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

More Related Contents:

  1. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  2. How to specify if a field is optional or required in OpenAPI/Swagger?
  3. How to return an array of objects in SwaggerHub?
  4. How to document dynamic query parameter names in OpenAPI (Swagger)?
  5. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  6. How to define a property that can be string or null in OpenAPI (Swagger)?
  7. Swagger schema properties ignored when using $ref – why?
  8. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  9. Swagger 2.0: Multiple Path objects with different paths but same request and response
  10. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  11. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  12. Swagger: wildcard path parameters
  13. How to define an optional parameter in path using swagger
  14. Swagger: “equivalent path already exists” despite different parameters
  15. Re-using model with different required properties
  16. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  17. How not to copy-paste 3 generic error responses in almost all paths?
  18. Schema object without a type attribute in Swagger 2.0
  19. Swagger: take one or more values from enum
  20. Swagger Inheritance and Composition
  21. Swagger/OpenAPI mock server
  22. Swagger: map of
  23. Use object type query param in swagger documentation
  24. Swagger complex response model with dynamic key value hash maps
  25. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  26. OpenAPI query string parameter with list of objects
  27. OpenAPI path/query parameters nested structure serialization
  28. Combining defintions in Swagger docs
  29. How to document default None/null in OpenAPI/Swagger using FastAPI?
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment