What is the 'scopes' field of the swagger security scheme object used for?

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

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?

Solution

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

Comments

[lfree]

Thank you very much, @Arnaud! BTW, I had already been planned to read your "writing-openapi-swagger-specification-tutorial" series! :)

[user]

@Arnaud Lauret I added scopes as mentioned by you .But my google endpoint is allowing acces even if the scopes dont match.What i might be doing wrong ?

[Ilario]

@Arnaud adding scopes to an operation seems to have no effect in Swagger UI: all the scopes are shown, none is selected. Even feeding a non-existent scope doesn't raise any error. Do you think it's a Swagger UI bug?