What is the field of the "areas" of the swagger security object?

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 an example of securityDefinitions from the Swagger Specification . What is meant for write: pets and for reading: ptes ? Are these some categories for paths?

+5
source share
1 answer

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

Oauth2 Areas

When the API is protected by Oauth, scopes are used to provide various user rights / privileges to the API. Areas are defined by name (you can use whatever you want).

Oauth allows authorization in SwaggerUI , which can act as an API consumer: enter image description here

In this case, this oauth2 protected API offers two areas:

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

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

But only defining this area is useless unless you declare which operations (s) are covered by these areas. This is done by adding this to the operation:

  security: - petstore_auth: - read:pets 

In this example, the operation is available to the API user only if he is allowed to use the read:pets scope. Note that a single operation may belong to several areas of oauth2, as well as to several security definitions.

Read more about security in OpenAPI (fka. Swagger) here

Categorization of OpenAPI operations (fka. Swagger)

Regardless of the scope of OAuth2, if you need to classify API operations, you can use tags :

  tags: - pets 

By adding this to the operation, it will be placed in the pets category. One operation can belong to several categories.

Partition categories are used by SwaggerUI to rearrange operations. In the screenshot below, we see 3 categories (pet, store and user): enter image description here Here you can find out more about the categories:

Here's a complete example using Oauth2 areas and categories

 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 
+9
source

All Articles