José Roberto Araújo for Emerging Code

Posted on May 24, 2024 • Edited on May 30, 2024

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.

Referências

Bring your solution into Docusign. Reach over 1.6M customers.

Docusign is now extensible. Overcome challenges with disconnected products and inaccessible data by bringing your solutions into Docusign and publishing to 1.6M customers in the App Center.

Learn more