如何在OpenAPI 3.0中定义标头参数? [英] How to define header parameters in OpenAPI 3.0?

问题描述

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

In OpenAPI (Swagger) 2.0, we could define header parameters like so:

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

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

But in OpenAPI 3.0.0, parameters are replaced by request bodies, and I cannot find a way to define header parameters, which would further be used for authentication.

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

What is the correct way to define request headers in OpenAPI 3.0.0?

推荐答案

在OpenAPI 3.0中，标头参数的定义与OpenAPI 2.0中的定义相同，只是type被替换为schema:

In OpenAPI 3.0, header parameters are defined in the same way as in OpenAPI 2.0, except the type has been replaced with schema:

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

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

When in doubt, check out the Describing Parameters guide.

但是在Swagger 3.0.0中，参数已被请求正文取代.

But in Swagger 3.0.0 parameters are replaced by request bodies.

这仅适用于形式参数和主体参数.其他参数类型(路径，查询，标头)仍定义为parameters.

This is only true for form and body parameters. Other parameter types (path, query, header) are still defined as parameters.

定义标头参数，该参数将进一步用于身份验证.

define header parameters, which would further be used for authentication.

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

A better way to define authentication-related parameters is to use securitySchemes rather than define these parameters explicitly in parameters. Security schemes are used for parameters such as API keys, app ID/secret, etc. In your case:

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

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

这篇关于如何在OpenAPI 3.0中定义标头参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！