Swagger

Swagger é uma ferramenta open source baseada na especificação OpenAPI que padroniza, documenta e facilita o teste de APIs RESTful de maneira interativa. O Swagger oferece um conjunto de utilitários que agilizam o desenvolvimento e a integração de sistemas, garantindo que tanto desenvolvedores quanto usuários compreendam e testem os serviços de forma prática.

O que é o Swagger?

Swagger engloba um conjunto de ferramentas que permitem a criação e manutenção de APIs de forma clara e padronizada. Seus principais componentes são:

Swagger Editor: Ambiente para criação e edição de arquivos de especificação (YAML ou JSON) da API, com validação em tempo real.
Swagger UI: Interface web interativa que gera a documentação visual da API e permite a execução de testes diretamente do navegador.
Swagger Codegen: Ferramenta que gera código-fonte em diversas linguagens, facilitando a criação de clientes e servidores a partir da especificação da API.

Por que ter uma boa documentação ?

Onboarding Rápido: Uma documentação clara reduz o tempo que novos integrantes levam para entender a arquitetura, fluxos de dados e convenções do projeto.
Redução de Erros: Especificações bem descritas evitam mal-entendidos sobre como a API deve se comportar, reduzindo bugs e retrabalho em correções.
Fácil Integração: Permite outros desenvolvedores consumir a API mais rápido quando encontram exemplos de requisições, respostas e códigos de erro bem definidos

Como usar?

1. Usando Swagger Editor (Design First)

Acesse https://editor.swagger.io
Escreva uma especificação OpenAPI em YAML ou JSON
Vizualize e edite os endpoint em tempo real
Exporte o arquivo para usar no Swagger UI or para gerar o código fonte usando o Swagger Codegen

2. Anotações de código (Code first)

Utilizando bibliotecas específicas para cada linguagem e framework, é possível inserir anotações, decorators ou comentários estruturados no código para gerar automaticamente a especificação Swagger/OpenAPI. Este método depende de que linguagem de programação será utilizada no projeto. Aqui estão alguns exemplos de como gerar a documentação da API através de comentários no código fonte:

Kotlin + Spring Boot

Adicione no build.gradle.kts:

implementation("org.springdoc:springdoc-openapi-ui:1.6.14")

Use anotações no código:

@RestController
@RequestMapping("/clientes")
@Tag(name = "Clientes", description = "Operações com clientes")
class ClienteController {

    @Operation(summary = "Lista clientes", description = "Retorna todos os clientes cadastrados")
    @ApiResponse(responseCode = "200", description = "Lista de clientes retornada com sucesso")
    @GetMapping
    fun listarClientes(): List<Cliente> {
        return clienteService.todos()
    }
}

Go + Gin Gonic e `swaggo/swag`

Instale as ferramentas usando o gerenciador de pacotes:

go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

Adicione comentários sobre seus handlers

// @Summary Lista todos os produtos
// @Description Retorna uma lista de produtos
// @Tags produtos
// @Produce json
// @Success 200 {array} Produto
// @Router /produtos [get]
func ListarProdutos(c *gin.Context) {
    produtos := []Produto{{Nome: "Camisa", Preco: 59.90}}
    c.JSON(http.StatusOK, produtos)
}

Gere a documanetação
```
swag init
```

Configure seu main.go

r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

Gerar código usando Swagger Codegen

O Swagger Codegen é uma ferramenta de linha de comando que permite gerar código-fonte automaticamente para APIs REST com base em uma especificação OpenAPI 2.0 (Swagger). Ele suporta dezenas de linguagens de programação e frameworks.

Instalar Swagger Codegen

Baixe o JAR mais recente do repositório oficial
Execute com:
```
java -jar swagger-codegen-cli.jar help
```

Gerar esqueleto da aplicação

Após criar seu arquivo de especificação OpenAPI, para criar o código fonte execute o comando:

swagger-codegen generate \
  -i swagger.yaml \
  -l python \
  -o cliente-python

Parâmetros:

-i: caminho para o arquivo OpenAPI
-l: linguagem alvo (use swagger-codegen langs para listar todas)
-o: pasta onde o código será gerado

Componentes em Destaque

Swagger Editor

O Swagger Editor é uma ferramenta online que facilita a criação e modificação da especificação da API. Ele apresenta:

Validação Automática: Detecta erros e inconsistências no arquivo YAML ou JSON em tempo real.
Interface Intuitiva: Permite uma edição simples e visual da especificação, auxiliando na compreensão dos componentes da API.
Visualização Lado a Lado: Exibe o código da especificação e sua representação visual simultaneamente.

Swagger UI

O Swagger UI converte a especificação da API em uma documentação interativa, permitindo:

Visualização Detalhada: Exibição organizada dos endpoints, parâmetros e respostas.
Testes Práticos: Execução de chamadas diretamente na interface, possibilitando a validação dos comportamentos dos endpoints.
Simulação de Autenticação: Permite testar APIs protegidas com diferentes mecanismos de autenticação.

Fluxo de Trabalho com Swagger

Um fluxo de trabalho típico usando Swagger envolve:

Design da API: Criar especificação no Swagger Editor (YAML/JSON).
Validação: Verificação da consistência da especificação.
Geração de Documentação: Criação automática da documentação interativa com Swagger UI.
Desenvolvimento: Implementação da API.
Testes: Validação dos endpoints usando a interface interativa do Swagger UI.
Iteração: Atualizar especificação conforme evolução da API.

Vantagens do Uso do Swagger

✅ Documentação Interativa: Facilita a compreensão e o teste dos endpoints sem a necessidade de ferramentas adicionais.
✅ Padronização e Consistência: A especificação OpenAPI garante que a documentação seja clara e uniforme.
✅ Agilidade no Desenvolvimento: A validação em tempo real reduzem erros e aceleram a implementação das APIs.
✅ Facilidade na Integração: Uma documentação detalhada e interativa melhora a comunicação entre equipes e sistemas.
✅ Design-first: Permite definir o contrato da API antes da implementação, garantindo alinhamento entre equipes.

Exemplos de Aplicação

Além de ser uma ferramenta indispensável para desenvolvedores profissionais, o Swagger é amplamente utilizado em diversos contextos:

Empresas de Software: Para documentação e padronização de APIs internas e externas.
Ambientes Educacionais: Como ferramenta didática para ensinar conceitos de APIs RESTful.
Projetos Open Source: Para facilitar a adoção e contribuição de novos desenvolvedores.
APIs Públicas: Para oferecer documentação de qualidade a desenvolvedores externos.

Melhores Práticas ao Usar Swagger

Mantenha a Especificação Atualizada: Garanta que a documentação reflita o estado atual da API.
Use Descrições Claras: Forneça descrições detalhadas para endpoints, parâmetros e modelos.
Adicione Exemplos: Inclua exemplos de requisições e respostas para facilitar o entendimento.
Documente Erros: Detalhe os possíveis códigos de erro e suas causas.
Versione sua API: Inclua informações de versionamento na especificação.

Conclusão

O Swagger é uma ferramenta poderosa e versátil para documentar e testar APIs, promovendo uma abordagem interativa e padronizada para o desenvolvimento de serviços. Sua utilização facilita tanto o trabalho colaborativo entre equipes quanto o aprendizado em ambientes educativos, garantindo que os conceitos de desenvolvimento de APIs sejam aplicados de forma prática e eficiente.