Swagger é uma das ferramentas mais utilizadas para documentação de APIs, mas seu tempo pode estar chegando ao fim com a chegada do Scalar UI.
Contexto histórico do Swagger
A história de uso do Swagger como ferramenta para documentação OpenAPI começa com a sua criação em 2010 por Tony Tam, enquanto trabalhava na empresa Reverb Technologies. Desde o início, seu objetivo era simplificar o processo de documentação de APIs para desenvolvedores.
Com o Swagger, era possível criar uma interface amigável para APIs RESTful, permitindo aos desenvolvedores entender o funcionamento de uma API sem precisar mexer no código fonte. Além disso, o Swagger também permite testar a API diretamente no navegador, o que economiza tempo e esforço dos desenvolvedores.
Em 2015, a Swagger foi doada para a Linux Foundation e se tornou parte do projeto OpenAPI. Juntamente com outras ferramentas, o Swagger ajudou a definir o padrão OpenAPI para documentação de APIs. Resultando na UI que já estamos acostumados a trabalhar por anos:
Apesar de sua popularidade e amplo uso, a UI do Swagger também tem suas limitações. Por exemplo, durante todo esse tempo a UX do Swagger permaneceu praticamente a mesma, além de não permitir uma documentação que contivesse textos explicativos sobre os endpoints da API.
Scalar como alternativa na documentação OpenAPI
O Scalar é uma ferramenta que vem servir como alternativa para documentação de APIs usando a especificação OpenAPI. Lançado recentemente, o Scalar se destaca por sua interface de usuário moderna e intuitiva, permitindo criar documentações contendo textos declarativos e explicativos sobre o negócio, funcionalidades, payloads e muitas outras formas de documentar uma API.
A interface do Scalar é limpa e simplificada, tornando-a mais acessível para qualquer pessoa que tenha interesse ou precise entender quais funcionalidades estão disponíveis em uma API. Além disso, o Scalar é mais rápido que o Swagger para documentar APIs complexas, graças ao seu eficiente mecanismo de renderização, além de disponibilizar opções de exemplos de uso das APIs em diversas linguagens e plataformas, o que traz bastante facilidade para quem está querendo usar uma API.
A integração do Scalar com a especificação OpenAPI significa que é possível importar e exportar documentação de API no formato OpenAPI, seja no formato json ou no formato yaml. Isso facilita a transição de outras ferramentas para o Scalar.
O Scalar também oferece integração com várias outras plataformas:
- .NET
- GO
- Rust
- NestJS
- Dentre outras que pode ser encontradas no repositório oficial do projeto
Durante esse artigo, vamos demonstrar o uso do Scalar em um projeto AspNet Core usando .NET 8.0.
Habilitando Scalar UI em um projeto AspNet Core 🚀
Para demonstrar o uso do Scalar em um projeto .NET, vamos considerar um projeto AspNet Core simples usando .NET 8.0, e que vai conter uma API para um sistema de gestão de hotéis.
⚠️ Se você está rodando seus projetos já usando o .NET 9.0, a versão do Scalar a ser usada será um outro pacote com um nome diferente do apresentado neste artigo, disponível no Nuget.
A versão que pode ser usada com o .NET 8.0 pode ser ou a 1.0.0 ou a 1.0.1-rc
Primeiro, precisamos adicionar o pacote Scalar ao nosso projeto através do NuGet:
dotnet add package AspNetCore.Scalar --version 1.0.1-rc
Em seguida, podemos configurar o Scalar em nosso arquivo Program.cs:
...
var app = builder.Build();
app.UseScalar(options =>
{
options.UseTheme(Theme.Default);
options.RoutePrefix = "api-docs";
});
...
No trecho de código acima, estamos configurando o Scalar para servir nossa documentação de API na rota "/api-docs".
💡 Para usar o Scalar você não precisa desinstalar o Swagger do seu projeto, pois ambos conseguem conviver lado a lado. Se você já tem o swagger instalado no seu projeto, basta instalar o pacote do Scalar e adicionar o código acima e o pacote vai saber localizar a Url Path do swagger contendo a documentação da API no formato OpenAPI.
Finalmente, podemos acessar nossa documentação de API navegando para "http://localhost:[PORTA_DEFINIDA]/scalar-api-docs" em um navegador de sua preferência. A partir daí, podemos interagir com nossa API diretamente da interface do Scalar.
Esse exemplo ilustra um pouco do que o Scalar pode trazer de melhorias para a documentação da API do seu projeto. Com sua interface moderna e recursos poderosos, o Scalar é uma excelente alternativa ao Swagger para documentação OpenAPI.
A imagem abaixo mostra o resultado da integração do Scalar em uma aplicação AspNet Core:
Perceba que a UI oferece uma experiência de usabilidade bastante diferente do que se está acostumado a ver com o Swagger. Além da UX diferente, também é possível realizar navegação pelas APIs e escolher uma plataforma para que o Scalar possa gerar um exemplo de código que se ajuste a sua necessidade, através das Client Libraries.
Scalar, .NET 9.0 e OpenAPI
O time do AspNet Core está trabalhando na implementação de um pacote oficial da Microsoft, o qual vai trabalhar entregando 100% das especificações OpenAPI. Nesse sentido, o pacote Swashbuckle será removido ❌ a partir do .NET 9.0, passando somente a ser possível utilizar o novo pacote: Microsoft.AspNetCore.OpenApi.
O pacote Scalar.AspNetCore, a partir da versão 1.0.1, será possível se integrar com as novidades que virão junto com o .NET 9.0 e a nova API de documentação, que trás um nome bastante óbvio: Microsoft.AspNetCore.OpenApi.
Validando sua especificação usando: Spectral
Spectral é um linter de documentos OpenAPI de código aberto. O pacote Spectral pode ser incorporado à construção de seu aplicativo para verificar a qualidade dos documentos OpenAPI gerados. Para instalar o Spectral siga as instruções através do repositório oficial.
Para tirar vantagens do Spectral você precisa realizar algumas configurações e instalar um pacote no seu projeto, antes de utilizar a ferramenta de Linter. Instale o pacote Microsoft.Extensions.ApiDescription.Server, ele vai permitir que seja gerada a documentação OpenAPI no momento do build do projeto.
dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease
Configure o seu projeto para gerar documentos no momento da compilação definindo as seguintes propriedades no arquivo .csproj do seu aplicativo:
<PropertyGroup>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>
Execute o build do seu projeto para que seja gerado o arquivo .json contendo as especificações das APIs:
dotnet build
Crie um arquivo .spectral.yml com o conteúdo abaixo:
extends: ["spectral:oas"]
Depois de tudo configurado e o arquivo .json com as especificações OpenAPI também gerado, você já pode executar o Linter contra suas especificações:
spectral lint [NOME_DO_SEU_ARQUIVO].json
...
The output will show any issues with the OpenAPI document.
output
1:1 warning oas3-api-servers OpenAPI "servers" must be present and non-empty array.
3:10 warning info-contact Info object must have "contact" object. info
3:10 warning info-description Info "description" must be present and non-empty string. info
9:13 warning operation-description Operation "description" must be present and non-empty string. paths./.get
9:13 warning operation-operationId Operation must have "operationId". paths./.get
✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)
## Conclusão 💭
Em conclusão, o Scalar surge como uma ferramenta poderosa e intuitiva para a documentação de APIs usando a especificação OpenAPI. Com uma interface moderna, opções de exemplos de uso das APIs em diversas linguagens e plataformas, e uma integração eficiente com a especificação OpenAPI, o Scalar tem a capacidade de melhorar significativamente a experiência de documentação de APIs.
Além disso, a integração com o Spectral, um linter de documentos OpenAPI de código aberto, possibilita a verificação da qualidade dos documentos OpenAPI gerados, assegurando uma documentação mais precisa e de qualidade superior. Portanto, o Scalar se apresenta como uma excelente alternativa ao Swagger para documentação OpenAPI.
## Referências
- [Scalar](https://scalar.com/)
- [Scalar for AspNet Core](https://github.com/scalar/scalar/blob/main/packages/scalar.aspnetcore/README.md)
- [Microsoft.AspNetCore.OpenApi](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/aspnetcore-openapi?view=aspnetcore-9.0&tabs=netcore-cli#using-scalar-for-interactive-api-documentation)
Top comments (6)
Como você configurou para gerar o json do OpenAPI?
Você pode ter acesso ao .json da sua api através do swagger. Por exemplo:
http://localhost:5096/swagger/v1/swagger.json
o
v1
está presente, se você estiver versionando a sua API.Sem utilizar Swagger é possível? Gostaria de deixar apenas uma lib
Usando o pacote Microsoft.OpenAPI
O Scalar tem algum hub onde possa se publicar especificação de APis de varios projetos ?
Sei que eles tem uma conta na cloud deles, mas não sei dizer se eles tem o que você precisa!