Introdução

  • 2 minutos

Há muitos benefícios em documentar o software que você cria. Uma documentação sólida não apenas torna seu código mais sustentável ao longo do tempo, mas também o torna mais consumível por outras pessoas. Tornar seu código mais consumível é especialmente importante quando você tem uma API que outras pessoas desejam usar. Felizmente, existem ferramentas e estruturas disponíveis que reduzem o custo de produção de boa documentação.

Suponha que você é o desenvolvedor-chefe de uma empresa de molduras para impressão. Sua empresa decidiu tornar suas APIs publicamente disponíveis. Muitas das APIs não têm nenhuma documentação existente e é sua responsabilidade documentá-las. A documentação das APIs facilita o uso correto por parte de seus parceiros, o que resulta em custos menores de suporte e manutenção.

Você precisa de uma forma fácil e padronizada de documentar cada API. Você também precisa de um método de hospedagem da documentação em um local acessível para os parceiros.

Neste módulo, você aprenderá como documentar uma API do ASP.NET Core existente usando Swashbuckle, Swagger, Swagger UI e OpenAPI.

Objetivos de aprendizagem

Neste módulo, você vai:

  • Saber mais sobre o Swashbuckle, OpenAPI e Swagger UI.
  • Habilitar o OpenAPI para uma API do C#/ASP.NET Core.
  • Usar o Swashbuckle em uma API do C#/ASP.NET Core.
  • Gerar e exibir a documentação da API com o OpenAPI.

Pré-requisitos

  • Experiência com design e implementação da API REST.
  • Experiência com desenvolvimento de aplicativos ASP.NET Core básicos.
  • Instalações locais do SDK do .NET, Visual Studio Code e a extensão do C# para Visual Studio Code.