swagger - 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的securityDefinitions示例。 写:pets 和 读:pets 有什么用途？那是路径的某些类别吗？

Answer 1

写入:宠物和读取:宠物是Oauth2 scopes，并且与OpenAPI(fka。Swagger)operations categorization不相关。
Oauth2范围
当使用Oauth保护API时，将使用范围为API使用者赋予不同的权限/特权。范围由名称定义(您可以使用任何名称)。
SwaggerUI中的Oauth范围授权可以充当API使用者:

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

写道:宠物:修改帐户中的宠物

阅读:宠物:阅读您的宠物

当使用OpenAPI(fka。Swagger)规范描述API时，您可以定义这些作用域，如问题所示。
但是，如果您不声明这些范围包含哪些操作，则仅定义这些范围是没有用的。
可以通过将其添加到操作中来完成:

     security:
        - petstore_auth:
          - read:pets

在此示例中，仅当API使用者被允许使用 read:pets范围时，该操作才可供API使用者访问。
请注意，单个操作可以属于多个oauth2范围，也可以属于多个安全性定义。
您可以在此处阅读有关OpenAPI(fka.Swagger)中的安全性的更多信息。

Security Scheme Object

Security Requirement Object object definition

Part 6 of my Writing OpenAPI (Swagger) Specification Tutorial about Security

OpenAPI(fka.Swagger)操作分类
无论OAuth2范围如何，如果您需要对API的操作进行分类，都可以使用 tags:

      tags:
        - pets

通过将其添加到操作中，它将被放置在 pets类别中。
单个操作可以属于多个类别。
这些类别由 SwaggerUI用于重新组合操作。在下面的屏幕截图中，我们可以看到3个类别(宠物，商店和用户):

您可以在此处阅读有关类别的更多信息:

Tag Object

Operation Object

Part 7 of my Writing OpenAPI (Swagger) Specification Tutorial about Documentation

这是使用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