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

前端 未结 1 2085
执念已碎
执念已碎 2021-02-15 07:08
petstore_auth:
  type: oauth2
  authorizationUrl: http://swagger.io/api/oauth/dialog
  flow: implicit
  scopes:
    write:pets: modify pets in your account
    read:pets         


        
相关标签:
1条回答
  • 2021-02-15 07:39

    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
    
    0 讨论(0)
提交回复
热议问题