The last thing we will demonstrate is describing the Replace Profile endpoint. This endpoint requires the user to be logged in and provides the token in the request.

But first, let's use everything we have learned so far to define the parameters, request bodies, and responses for the Replace Profile endpoint:

...
components:
 ...
 responses:
    Success:
      description: Success
    ...
    ErrorUnauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ...
  securitySchemes:
    token:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /users/{userId}/profile:
    put:
      tags:
        - Profile
      summary: Replaces the Profile of the User with a new Profile
      security:
        - token: []
      parameters:
        - name: userId
          in: path
          description: ID of the User
          required: true
          schema:
            type: string
      requestBody:
        description: The New Profile object
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Profile"
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '401':
          $ref: '#/components/responses/ErrorUnauthorized'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '415':
          $ref: '#/components/responses/ErrorUnsupportedMediaType'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'

Here, we have defined two new response:

•  Success, which is simply a 200 Success response with no payload
• ErrorUnauthorized, which should be returned if the Authorization header (containing our JSON Web Token) is not present

What's new is the securitySchemes we've defined under components at the root of the OpenAPI object. In OAS, a security scheme is a method for our client to authenticate themselves. Supported schemes are HTTP authentication, API key, OAuth2, and OpenID Connect Discovery. Since we are using the Bearer scheme in our HTTP Authorization header to authenticate, we have defined it as such.

In our Operation Object, we have also included a security property that states that this endpoint needs to be authenticated using the security scheme we've defined called token.