Documentando os paths da API (Parte 1)

Como já falado anteriormente, o arquivo do tipo yaml é tabulado, então é importante ter cuidado em sua criação para não haver erros.

Documentando as primeiras rotas

Inicialmente, serão documentadas duas rotas: a que retorna a lista de usuários e a que busca um usuário pelo id. Então, acompanhe a aula para obter todos os detalhes e informações e ao final é desejável que seu arquivo de documentação esteja como se vê abaixo:

openapi: '3.0.2'
info:
  title: IMD Blog API!
  version: '1.0'
  description: API do blog do IMD
  contact:
    name: Gustavo Leitão
servers:
  - url: http://localhost:8080/api
    description: Servidor de teste
paths:             
  /usuarios:
    get:
      operationId: getUsuarios
      summary: Obtém todos os usuários do sistema
      tags:
        - Usuários
      responses:
        '200':
          description: Lista de usuários
          content:
            appication/json:
              schema:
                type: object
                properties:
                  usuarios:
                    type: array
                    items:
                      $ref:  "#/components/schemas/Usuario"

  /usuarios/{id}:
    get:
      operationId: getById
      summary: Obtém um usuário a partir do id
      tags:
        - Usuários
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: Retorna um usuário
          content:
            appication/json:
              schema:
                type: object
                properties:
                  usuario:
                    type: object
                    $ref: "#/components/schemas/Usuario"

        '400':
          description: Bad Request
          content:
            appication/json:
              schema: 
                $ref:  "#/components/schemas/Erro"

components:
  schemas:
    Usuario:
      type: object
      properties:
        id:
          type: integer
          description: Id do usuário
          example: 9
        email:
          type: string
          description: E-mail do usuário
          example: foo@bar.com.br
    Erro:
      type: object
      properties:
        msg:
          type: string
          description: Mensagem de erro
          example: Usuário não encontrado!