swagger - swagger 安全方案对象的“范围”字段用于什么？

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

这是Swagger Specification中的 securityDefinitions 示例。write:pets和read:pets的用途是什么？这是路径的一些类别吗？

score 12 · Accepted Answer

write:pets和read:petsOauth2 scopes与 OpenAPI (fka. Swagger) 相关且不相关operations categorization。

Oauth2 范围

当使用 Oauth 保护 API 时，范围用于为 API 使用者提供不同的权利/特权。范围由名称定义（您可以使用任何您想要的名称）。

SwaggerUI中的Oauth 范围授权可以充当 API 使用者：

在这种情况下，这个 oauth2 安全 API 提出了 2 个作用域：

write: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 - swagger 安全方案对象的“范围”字段用于什么？

1 回答 1

Related

Reference