用于招摇安全方案对象的'范围'字段是什么？

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规范中的securityDefinitions示例.写的是什么:宠物和阅读:ptes用于什么？是路径的一些类别？

Answer 1

写:宠物和阅读:宠物是Oauth2 scopes和不相关的OpenAPI(FKA扬鞭)operations categorization.

Oauth2范围

使用Oauth保护API时,范围用于为API使用者提供不同的权限/特权.范围由名称定义(您可以使用任何您想要的).

Oauth在SwaggerUI中对范围进行授权,可以充当API使用者:

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

• 阅读:宠物:在您的帐户中修改宠物
• 写:宠物:读你的宠物

在使用OpenAPI(fka.Swagger)规范描述API时,您可以定义这些范围,如问题所示.

但是,如果您未声明这些范围涵盖哪些操作,则仅定义这些范围是无用的.通过将此添加到操作来完成:

     security:
        - petstore_auth:
          - read:pets

在此示例中,仅当允许API使用read:pets范围时,API操作员才能访问该操作. 请注意,单个操作可以属于多个oauth2范围,也可以属于多个安全性定义.

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

• 安全方案对象
• 安全要求对象对象定义
• 我写关于安全性的OpenAPI(Swagger)规范教程的第6部分

OpenAPI(fka.Swagger)操作分类

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

      tags:
        - pets

通过将其添加到操作中,它将被放入类别中pets.单个操作可以属于多个类别.

SwaggerUI使用这些类别重新组合操作.在下面的屏幕截图中,我们可以看到3个类别(宠物,商店和用户): 您可以在此处详细了解类别:

• 标记对象
• 操作对象
• 我编写关于文档的OpenAPI(Swagger)规范教程的第7部分

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