繁体   English   中英

如何避免每个api路径重复401错误响应? ( OpenApi 3 )

How is it possible to avoid the duplication of 401 error response for each api path? ( OpenApi 3 )

提示:本站收集StackOverFlow近2千万问答,支持中英文搜索,鼠标放在语句上弹窗显示对应的参考中文或英文, 本站还提供   中文繁体   英文版本   中英对照 版本,有任何建议请联系yoyou2525@163.com。

我在securitycomponents/securitySchemes定义了我的身份验证。 有关 responseSwagger 文档中,他们提供了以下示例:

paths:
  /something:
    get:
      ...
      responses:
        ...
        '401':
           $ref: '#/components/responses/UnauthorizedError'
    post:
      ...
      responses:
        ...
        '401':
          $ref: '#/components/responses/UnauthorizedError'
...
components:
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      headers:
        WWW_Authenticate:
          schema:
            type: string

我的路径多于两条,要访问其中任何一条,必须对客户端进行身份验证。 我想避免每个路径的“401”定义,并在全球范围内定义一次,如果可能的话。

如何为每条路径使用此响应?

'401':
  $ref: '#/components/responses/UnauthorizedError'
2 个回复

如果您希望响应显示在该特定端点上,则不能。

我通过不将它们添加到每个端点,而是将易于理解的标准响应 - 401、403、429、404、503 - 放在状态端点或根方法上来避免重复,以支持重要错误。 例如:

  '/{foo}/{bar}/status':
    get:
      tags:
        - api
      responses:
        '200':
          description: successful response with a resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/statusResponse'
        '400':
          $ref: '#/components/responses/400_error_response'
        '401':
          $ref: '#/components/responses/401_error_response'
        '403':
          $ref: '#/components/responses/403_error_response'
        '404':
          $ref: '#/components/responses/404_error_response'          
        '500':
          $ref: '#/components/responses/500_error_response'

样板响应将全部引用标准响应。

真正的端点通常有一个明确定义的响应,特定于该操作和可能出现特定错误的事情。

  '/{foo}/{bar}/segment':
    post:
      summary: checks username is found or not
      description: |-
        checks username and returns 204 if found else 403
      operationId: checkUsername
      tags:
        - Login
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/segment_POST_request'
      responses:
        '200':
          $ref: '#/components/responses/segment_POST_200_response'
        '403':
          $ref: '#/components/responses/403_forbidden_response'
        '500':
          $ref: 
 '#/components/responses/500_internal_server_error_replayable_response'

我确保的一件事是错误响应,该操作的可能错误代码包含在响应中,如下所示:

    500_internal_server_error_replayable_response:
      description: |-
        The following `500 Internal Server Error` errors can occur during the API processing.
        
        | errorCode | cause | details |
        | - | - | - |
        | `SOME.ERROR.500` | There was an error processing the request either in Foo or on a downstream system | A request to something failed, Bar or Baz however the error is recoverable and can be replayed |
        | `SOME.ERROR.014` | Baz returned a `404` during the migration operation, even though it has previously confirmed the member exists | This is a fatal error during the migration process and cannot be recovered. The request should not be replayed. |
      headers:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            status: '500'
            errorCode: SOME.ERROR.500
            errorDescription: The request could not be processed
            errorSubCode: ''
            furtherDetails: ''
            docLink: ''     

使用扩展将它们作为构建脚本的一部分自动添加。

您要做的不是 OpenAPI 标准的一部分。 响应不是从父对象继承的; 它们必须明确添加到每个端点。 您可以为每个响应包含一个$ref ,但是对于定义明确的具有许多端点的规范,您最终会得到很多重复,并且随着时间的推移,端点可能会错过一两个响应作为添加和修改制作。 另外,这根本不是一个好的创作体验。

为防止出现此问题,请为您的回复添加扩展名,如下所示:

responses:
  x-default-responses: true
  '418':
    description: Additional responses go here

上述规范将是您工作的规范。 完成后,让脚本扫描您完成的 yaml 文件,并将该行替换为您的默认响应列表。 将此修改后的规范用作开发过程的下一阶段(无论您使用 OpenAPI 规范是为了什么,无论是文档、测试还是 SDK 生成)。

虽然你可以有你的脚本中添加的响应,而不扩展特性(毕竟,它只是YAML你写的),我建议你不要这样做。 该扩展使您的意图清晰,因此其他编辑器将了解存在其他响应。 此外,很可能(现在或将来的某一天)您的端点可能不符合您的默认响应,因此您不希望意外添加这些端点。

1 Azure API管理:Open API(无订阅密钥)仍然显示错误401

我想设置一个开放的API,即不需要订阅密钥的API。 我已经创建了API,并将其关联到未选中并需要发布“需要订阅”的新产品。 但是,对该API的任何调用都将导致可怕的“ 401,因为缺少订阅密钥而导致访问被拒绝。向API发出请求时,请确保包括订阅密钥。” 我想念什么? 在将此 ...

2 当 API 以 401 响应过期会话时,避免多个错误通知

我的自定义 react-admin 页面有一个组件可以进行多个 API 调用。 当会话过期并且所有调用都以 401 状态响应时,我被重定向到登录,但通知出现多次(每次失败调用一次)。 调用是使用专门的钩子进行的。 有没有办法让这些通知静音? 查看 react-admin 代码,我认为这是不可能的 ...

3 使用NTLM避免每个请求的401响应

我们这里有一个使用基于NTLM的Windows身份验证的asp.net 3.5应用程序。 该系统在专用网络上运行,该网络实际上分布在不同的地理位置(通过VPN连接)。 我们现在正在尝试优化网站的性能。 由于NTLM的工作方式,每个对IIS的新请求由3个不同的请求组成,而前2个是401个 ...

6 基于路径参数的备用API响应模式的OPENAPI 3 JSON结构是什么

对于在以下情况下如何编写json API文档,我有些困惑: 对于我们的GET,我们希望有一个允许“摘要”响应模式或“详细”响应模式的path参数。 我在某些地方看到过,您可以使用oneOf以某种方式指定两个响应模式,并且我看到了一些基于内容类型的示例,但没有基于path参数的示例。 所以我对GE ...

8 iPhone的Twitter API中的错误响应401

我正在将api集成到我的应用程序中。 当我尝试鸣叫时,我收到一个错误请求401,似乎是“身份验证凭据丢失或不正确”。 如何清除此错误? 谢谢 ...

2011-06-15 14:49:39 0 112   twitter
9 Blogger api始终返回401错误响应

我使用Volley在我的Android应用程序中发送HTTP请求。 我在互联网上寻找了一些答案但却找不到任何答案。 我使用Blogger API并发送HTTP请求以使用文档中给出的URL方法获取博客来获取我的博客 获取https://www.googleapis.com/bl ...

暂无
暂无

声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.

 
粤ICP备18138465号  © 2020-2022 STACKOOM.COM