Scalar: Documentação OpenAPI Moderna
Tags: openapi, apifirst, swagger
Published: 2024-05-24 14:34:35

> 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:


![Swagger UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qmsa3d1hrvqk2rdoxmk6.png)



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](https://github.com/scalar/scalar)

> **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](https://www.nuget.org/packages/Scalar.AspNetCore).

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:

```csharp
dotnet add package AspNetCore.Scalar --version 1.0.1-rc
```

Em seguida, podemos configurar o Scalar em nosso arquivo Program.cs:

```csharp
...

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](http://localhost:5096/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:

![Scalar](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r4kc5m8qn6rpsdh67ocm.png)

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](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/aspnetcore-openapi?view=aspnetcore-9.0&tabs=visual-studio#using-scalar-for-interactive-api-documentation).**

## 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](https://github.com/stoplightio/spectral).

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.

```csharp
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:

```xml
<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:

```csharp
dotnet build
```

Crie um arquivo .spectral.yml com o conteúdo abaixo:

```yaml
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:

```bash
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)