在 OpenAPI 3 中，如何记录需要具有指定值的 Accept header 才能成功调用 API？

Question

对于我为了成功验证而记录的遗留 API，我需要提供以下 headers：

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 header 必须包含 application/json; version=public/v2 任何其他内容 returns 406 Not Acceptable header.

此外，header Accept 值 application/json; version=public/v2 应该在我的请求中。响应 header 总是 application/json.

你知道我如何记录吗？

Answer 1

在 OpenAPI 3.0 中，request header Accept 和 response header 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`)

Answer 2

为了指定您应该使用 application/json; version=public/v2 接受 header 执行 http 请求，您应该像这样记录它：

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'
   
  responses:
    406:
      description: "Is returned once `Accept` header has not been provided or does not contain the `application/json; version=public/v2` value."
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: 'boolean'
              type:
                type: 'string'
              message:
                type: 'string'
                description: "Your access token is either missing or incorrect. Please check the X-Access-Token header and try again."
    401:
      description: "Is returned once `X-Access-Token` has not been provided"
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: 'boolean'
              type:
                type: 'string'
              message:
                description: "Your access token is either missing or incorrect. Please check the X-Access-Token header and try again."
security:
  - ApiKey: []  

paths:
   /myendpoint:
     put:
       requestBody:
         required: true
         content: 
           'application/json; version=public/v2': {}
         
       responses:
         200:
            'application/json':
               #your response jhere as documented in
         406:
           $ref: '#/components/responses/406'
         401:
           $ref: '#/components/responses/401'

因此，使用这种方法，您在文档中告诉请求应该是一个 put 带有 Accept header application/json; version=public/v2 的带有任何（或没有）参数的请求.

尽管 get 请求 requestBody 不是有效定义。

在 OpenAPI 3 中，如何记录需要具有指定值的 Accept header 才能成功调用 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?

openapi