Documentando a autenticação da API

É válido ressaltar que o nosso projeto possui uma forma de login e é importante documentar essa parte também. Além disso, outras rotas dependem da autenticação para funcionar. Então, devemos documentar o tipo de autenticação e como se faz o login.

Acompanhe a aula para compreender melhor as alterações que serão feitas.

Documentando o tipo de autenticação

Acessando a documentação do Swagger, podemos ver o tipo de autenticação que fizemos, que é JWT, usando o padrão Bearer Authentication.

Sabendo disso, é preciso seguir a documentação do Swagger para inserir as linhas no arquivo yaml. Abaixo é possível encontrar os comandos a serem inseridos:

# 1) Define the security scheme type (HTTP bearer)
components:
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes
# 2) Apply the security globally to all operations
security:
  - bearerAuth: []         # use the same name as above

Documentando como se faz um login

A parte de logar é em '/usuario/login', sendo um path no arquivo. Então, é preciso documentar.

Veja abaixo a documentação do login:

/usuarios/login:
    post:
      operationId: userLogin
      summary: Realiza autenticação na API
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: foo@bar.com
                senha:
                  type: string
                  example: algosecreto
      tags:
        - Autenticação
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjUsImlzcyI6ImltZC1iYWNrZW5kIiwiYXVkIjoiaW1kLWZyb250ZW5kIiwiZW1haWwiOiJuZXd0b25AZ21haWwuY29tIiwia
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/Erro"