摇摇欲坠的安全方案对象的“作用域"字段是做什么用的? [英] What is the 'scopes' field of the swagger security scheme object used for?
问题描述
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示例. write:pets 和 read:ptes 有什么用途?那是路径的某些类别吗?
This is a securityDefinitions example from the Swagger Specification. What does the write:pets and read:ptes intended for? Is that some categories for the paths?
推荐答案
write:pets 和 read:pets 是Oauth2 scopes，与OpenAPI不相关(fka昂首阔步)operations categorization.
write:pets and read:pets are Oauth2 scopes and are not related to OpenAPI (fka. Swagger) operations categorization.
Oauth2范围
当使用Oauth保护API时，作用域用于为API使用者提供不同的权限/特权.范围由名称定义(您可以使用任何名称).
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范围授权可以充当API使用者:
Oauth scopes authorization in SwaggerUI which can act as an API consumer:
在这种情况下，此oauth2安全API提出了2个范围:
In this case this oauth2 secured API propose 2 scopes:
- 阅读:宠物:修改您帐户中的宠物
- write:pets:阅读您的宠物
使用OpenAPI(fka.Swagger)规范描述API时，您可以按照问题所示定义这些范围.
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
在此示例中，仅当API使用者被允许使用read:pets范围时，该操作才可供API使用者访问.
请注意，单个操作可以属于多个oauth2范围，也可以属于多个安全性定义.
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.
您可以在此处阅读有关OpenAPI(fka.Swagger)中安全性的更多信息
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)操作分类
无论OAuth2范围如何，如果您需要对API的操作进行分类，都可以使用tags:
Regardless of OAuth2 scope, if you need to categorize an API's operations, you can use tags:
tags:
- pets
通过将其添加到操作中，它将被放置在类别pets中.
一个操作可以属于多个类别.
By adding this to an operation it will be put in the category pets.
A single operation can belong to multiple categories.
这些类别用于 SwaggerUI 来重新分组操作.在下面的屏幕截图中，我们可以看到3个类别(宠物，商店和用户): 您可以在此处阅读有关类别的更多信息:
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
以下是使用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
这篇关于摇摇欲坠的安全方案对象的“作用域"字段是做什么用的?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
