在OpenAPI3中，如何记录具有指定值的Accept标头对于成功的API调用是必需的？ [英] In OpenAPI 3, how to document that an Accept header with a specified value is necessary on request in order for a successful API call?

问题描述

对于我为成功进行身份验证而记录的旧版API，我需要提供以下标头：

X-Access-Token: {token}
Accept: application/json; version=public/v2

对于我需要的令牌部分，通过以下方式记录：

openapi: 3.0.0
info:
  version: "v2"
  title: Company App Public Api
  description: Integrate your platform with company app website

components:
  securitySchemes:
    ApiKey:
      type: 'apiKey'
      in: 'header'
      name: 'X-Access-Token'
security:
  - ApiKey: []  

我需要提供一个Accept: application/json; version=public/v2，但我如何才能记录这一点，以便进行身份验证。Accept标头必须包含application/json; version=public/v2任何其他返回的406 Not Acceptable标头。

此外，值为application/json; version=public/v2的标头Accept应该在我的请求中。响应头始终为application/json。

你知道我怎样才能记录下来吗？

推荐答案

OpenAPI3.0中将请求头部Accept和响应头部Content-Type都定义为responses.<code>.content.<Accept value>。这需要在每个操作中定义。

paths:
  /something:
    get:
      responses:
        '200':
          description: Successful operation
          content:
            'application/json; version=public/v2':  # <-----
              schema:
                ...
         '406':
           description: Invalid media type was specified in the `Accept` header (should be `application/json; version=public/v2`)

这篇关于在OpenAPI3中，如何记录具有指定值的Accept标头对于成功的API调用是必需的？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！