Para que é que o Swagger é utilizado?

O Swagger (agora Especificação OpenAPI) é utilizado para descrever, documentar e visualizar APIs RESTful. Isto permite que desenvolvedores, testadores e consumidores de API compreendam a funcionalidade do serviço sem acesso ao código fonte.

Principais funções:

1. Documentação: Criação automática de documentação interativa da API.
2. Desenvolvimento: Ajuda no desenvolvimento da API, fornecendo uma definição clara do contrato.
3. Testes: A interface Swagger (Swagger UI) permite testar endpoints de API diretamente do navegador.
4. Geração de código: Pode gerar código cliente (SDK) ou stubs de servidor com base na especificação OpenAPI.
5. Design: Pode ser usado como uma ferramenta para projetar a API antes de começar a codificar (Abordagem de Design-First).

Exemplo de fragmento de especificação em formato YAML:

# Descrição curta da API
openapi: 3.0.0
info:
  title: Minha API de teste
  version: 1.0.0
paths:
  /items:
    get:
      summary: Obter a lista de todos os elementos
      responses:
        '200':
          description: Lista de elementos obtida com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

Isto garante a consistência entre as diferentes partes envolvidas no desenvolvimento e uso da API.