swagger 安全方案对象的 'scopes' 字段是做什么用的？

Question

petstore_auth:
  type: oauth2
  authorizationUrl: http://swagger.io/api/oauth/dialog
  flow: implicit
  scopes:
    write:pets: modify pets in your account
    read:pets: read your pets

这是来自 the Swagger Specification 的安全定义示例。 write:pets 和 read:pets 的用途是什么？这是路径的某些类别吗？

Answer 1

write:pets 和 read:pets 是 Oauth2 scopes 并且与 OpenAPI 无关（ fka.Swagger) operations categorization.

Oauth2 范围

当 API 使用 Oauth 保护时，范围用于向 API 消费者提供不同的 rights/privilege。范围由名称定义（您可以使用任何您想要的名称）。

Oauth 在 SwaggerUI 范围内授权，可以充当 API 消费者：

在这种情况下，此 oauth2 安全 API 提议 2 个范围：

write:pets: 修改您账户中的宠物
read:pets：阅读你的宠物

使用 OpenAPI (fka.Swagger) 规范描述 API 时，您可以按照问题中所示定义这些范围。

但是，如果您不声明这些范围涵盖了哪些操作，则只定义这些范围是没有用的。这是通过将此添加到操作来完成的：

     security:
        - petstore_auth:
          - read:pets

在此示例中，仅当 API 使用者被允许使用 read:pets 范围时，该操作才可供他访问。 请注意，单个操作可以属于多个 oauth2 范围以及多个安全定义。

您可以在此处阅读有关 OpenAPI (fka.Swagger) 安全性的更多信息

OpenAPI (fka.Swagger) 操作分类

无论 OAuth2 范围如何，如果您需要对 API 的操作进行分类，您可以使用 tags:

      tags:
        - pets

通过将此添加到操作，它将被放入类别 pets。单个操作可以属于多个类别。

SwaggerUI 使用这些类别来重新组合操作。在下面的屏幕截图中，我们可以看到 3 个类别（宠物、商店和用户）：您可以在此处阅读有关类别的更多信息：

这是使用 Oauth2 范围和类别的完整示例

swagger: "2.0"
info:
  version: "1.0.0"
  title: Swagger Petstore

securityDefinitions:
  petstore_auth:
    type: oauth2
    authorizationUrl: http://petstore.swagger.io/api/oauth/dialog
    flow: implicit
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

paths:
  /pets/{petId}:
    parameters:
      - in: path
        name: petId
        description: ID of pet that needs to be fetched
        required: true
        type: integer
        format: int64
    get:
      tags:
        - pets
      summary: Find pet by ID
      responses:
        "404":
          description: Pet not found
        "200":
          description: A pet
          schema:
            $ref: "#/definitions/Pet"
      security:
        - petstore_auth:
          - read:pets
    delete:
      tags:
        - pets
      summary: Deletes a pet
      responses:
        "404":
          description: Pet not found
        "204":
          description: Pet deleted
      security:
        - petstore_auth:
          - write:pets

definitions:
  Pet:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        example: doggie

swagger 安全方案对象的 'scopes' 字段是做什么用的？

What is the 'scopes' field of the swagger security scheme object used for?

swagger

openapi