如何在OpenAPI 3.0中定义标头参数？

Question

在OpenAPI(Swagger)2.0中,我们可以像这样定义头参数:

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username

但是在OpenAPI 3.0.0中,参数被请求体替换,我找不到定义头参数的方法,这将进一步用于身份验证.

在OpenAPI 3.0.0中定义请求标头的正确方法是什么？

Answer 1

在OpenAPI 3.0中,标题参数的定义方式与OpenAPI 2.0相同,但type已被替换为schema:

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username
          schema:
            type: string

如有疑问,请查看" 描述参数"指南.

但在Swagger 3.0.0中,参数被请求体替换.

这仅适用于表格和身体参数.其他参数类型(路径,查询,标题)仍定义为parameters.

定义头参数,这将进一步用于身份验证.

定义与身份验证相关的参数的更好方法是使用securitySchemes而不是显式定义这些参数parameters.安全方案用于API密钥,应用程序ID /机密等参数.在您的情况下:

components:
  securitySchemes:
    usernameHeader:
      type: apiKey
      in: header
      name: X-Username

paths:
  /post:
    post:
      security:
        - usernameHeader: []
      ...