swagger 安全方案对象的“范围"字段用于什么? [英] What is the 'scopes' field of the swagger security scheme object used for?

问题描述

petstore_auth:类型:oauth2授权网址:http://swagger.io/api/oauth/dialog流:隐式范围:write:pets: 修改你账户里的宠物阅读:宠物:阅读你的宠物

这是来自

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

• write:pets:修改您帐户中的宠物
• read:pets:阅读你的宠物

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

但是，如果您不声明这些范围涵盖哪些操作，则仅定义这些范围是没有用的.这是通过将其添加到操作来完成的:

 安全性:- petstore_auth:- 阅读:宠物

在此示例中，API 使用者只有在被允许使用 read:pets 范围的情况下才能访问该操作.请注意，单个操作可以属于多个 oauth2 范围，也可以属于多个安全定义.

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

• 您可以在此处阅读有关类别的更多信息:
  • 标签对象
  • 操作对象
  • 我编写 OpenAPI (Swagger) 规范的第 7 部分文档教程

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

  招摇:2.0"信息:版本:1.0.0"；标题:招摇宠物店安全定义:petstore_auth:类型:oauth2授权网址:http://petstore.swagger.io/api/oauth/dialog流:隐式范围:write:pets: 修改你账户里的宠物阅读:宠物:阅读你的宠物路径:/宠物/{petId}:参数:- 在:路径名称:宠物身份描述:需要获取的宠物ID要求:真类型:整数格式:int64得到:标签:- 宠物摘要:通过ID查找宠物回复:404":描述:未找到宠物200":描述:一只宠物架构:$ref: "#/definitions/Pet";安全:- petstore_auth:- 阅读:宠物删除:标签:- 宠物摘要:删除宠物回复:404":描述:未找到宠物204":描述:宠物已删除安全:- petstore_auth:- 写:宠物定义:宠物:类型:对象特性:ID:类型:整数格式:int64名称:类型:字符串例子:小狗

  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
  

  This is a securityDefinitions example from the Swagger Specification. What does the write:pets and read:pets intended for? Is that some categories for the paths?

  解决方案

  write:pets and read:pets are Oauth2 scopes and are not related to OpenAPI (fka. Swagger) operations categorization.

  Oauth2 scopes

  When an API is secured with Oauth, scopes are used to give different rights/privilege to the API consumer. Scopes are defined by a name (you can use whatever you want).

  Oauth scopes authorization in SwaggerUI which can act as an API consumer:

  In this case this oauth2 secured API propose 2 scopes:

  • write:pets: modify pets in your account
  • read:pets: read your pets

  When describing an API with an OpenAPI (fka. Swagger) specification, you can define these scopes as shown in the question.

  But only defining these scope is useless if you do not declare which operation(s) is covered by these scopes. It is done by adding this to an operation:

       security:
          - petstore_auth:
            - read:pets
  

  In this example, the operation is accessible to the API consumer only if he was allowed to use the read:pets scope. Note that a single operation can belong to multiple oauth2 scopes and also multiple security definitions.

  You can read more about security in OpenAPI (fka. Swagger) here

  • Security Scheme Object
  • Security Requirement Object object definition
  • Part 6 of my Writing OpenAPI (Swagger) Specification Tutorial about Security

  OpenAPI (fka. Swagger) operation categorization

  Regardless of OAuth2 scope, if you need to categorize an API's operations, you can use tags:

        tags:
          - pets
  

  By adding this to an operation it will be put in the category pets. A single operation can belong to multiple categories.

  Theses categories are used by SwaggerUI to regroup operations. In the screen capture below, we can see 3 categories (pet, store and user): You can read more about categories here:

  • Tag Object
  • Operation Object
  • Part 7 of my Writing OpenAPI (Swagger) Specification Tutorial about Documentation

  Here's the full example using Oauth2 scopes and a category

  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 安全方案对象的“范围"字段用于什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！