Scalar: Documentação OpenAPI Moderna

#openapi #apifirst #swagger

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.