Ícone de mensagem
Ir para o conteúdo do rodapé
  1. IronPDF
  2. Blog do IronPDF
  3. Ajuda do .NET
  4. OpenAPI .NET
AJUDA DO .NET

OpenAPI .NET (Como funciona para desenvolvedores)

Curtis Chau
Curtis Chau
Atualizado:

OpenAPI, anteriormente conhecido como Swagger, é uma especificação para construir e descrever APIs RESTful. Ele permite que os desenvolvedores definam a estrutura de suas APIs em um formato padronizado, possibilitando que diversas ferramentas e serviços entendam e interajam com a API REST de forma eficaz e forneçam feedback. No ecossistema .NET, a integração do OpenAPI .NET é facilitada por meio de diversas bibliotecas e ferramentas que tornam mais fácil criar, documentar e consumir APIs.

Neste artigo, aprenderemos sobre as especificações de suporte do OpenAPI e como criar um arquivo PDF usando o IronPDF e retorná-lo como resposta de uma chamada de API.

Configurando o OpenAPI no .NET

Para começar a trabalhar com um projeto OpenAPI .NET , normalmente você usa a biblioteca Swashbuckle, que gera a especificação ou documentação OpenAPI para suas APIs ASP.NET Core .

Passo 1: Instale o Swashbuckle

Primeiro, você precisa instalar o pacote Swashbuckle.AspNetCore via NuGet no Visual Studio. Você pode fazer isso usando o Console do Gerenciador de Pacotes NuGet :

Install-Package Swashbuckle.AspNetCore

Ou usando a CLI do .NET :

dotnet add package Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore
SHELL

Passo 2: Configurar o Swashbuckle

Em seguida, você precisa configurar o Swashbuckle em seu projeto ASP.NET Core . Isso envolve a atualização do arquivo Program.cs para adicionar serviços Swagger e configurar o middleware Swagger.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
// Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
// Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
Dim builder = WebApplication.CreateBuilder(args)

' Add services to the container.
builder.Services.AddControllers()
' Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer()
builder.Services.AddSwaggerGen()

Dim app = builder.Build()

' Configure the HTTP request pipeline.
If app.Environment.IsDevelopment() Then
	app.UseSwagger()
	app.UseSwaggerUI()
End If

app.UseHttpsRedirection()
app.UseAuthorization()
app.MapControllers()
app.Run()
$vbLabelText   $csharpLabel

Geração e visualização da documentação da API

Após configurar o Swashbuckle, a execução da sua aplicação irá gerar automaticamente a documentação OpenAPI. Você pode visualizar essas descrições OpenAPI navegando até a interface do Swagger UI .

Usando definições OpenAPI

As definições OpenAPI são ferramentas poderosas que podem ser usadas para gerar SDKs de cliente, testar APIs e garantir a consistência entre diferentes serviços. A especificação OpenAPI define uma interface padrão e independente de linguagem para APIs, que permite que tanto humanos quanto computadores compreendam as funcionalidades de um serviço sem acesso ao código-fonte.

Ampliando a API aberta com anotações personalizadas

O Swashbuckle permite que você aprimore sua documentação OpenAPI com anotações personalizadas. Essas anotações podem ser adicionadas diretamente aos seus controladores e modelos para fornecer informações adicionais sobre o comportamento e as estruturas de dados da API.

Exemplo: Anotações personalizadas

using Microsoft.AspNetCore.Mvc;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        [SwaggerOperation(Summary = "Gets the weather forecast for the next 5 days")]
        [SwaggerResponse(200, "Successfully retrieved weather forecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}
using Microsoft.AspNetCore.Mvc;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        [SwaggerOperation(Summary = "Gets the weather forecast for the next 5 days")]
        [SwaggerResponse(200, "Successfully retrieved weather forecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}
Imports Microsoft.AspNetCore.Mvc

Namespace WebApplication8.Controllers
	<ApiController>
	<Route("[controller]")>
	Public Class WeatherForecastController
		Inherits ControllerBase

		Private Shared ReadOnly Summaries() As String = { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }

		Private ReadOnly _logger As ILogger(Of WeatherForecastController)

		Public Sub New(ByVal logger As ILogger(Of WeatherForecastController))
			_logger = logger
		End Sub

		<HttpGet(Name := "GetWeatherForecast")>
		<SwaggerOperation(Summary := "Gets the weather forecast for the next 5 days")>
		<SwaggerResponse(200, "Successfully retrieved weather forecast")>
		Public Function [Get]() As IEnumerable(Of WeatherForecast)
			Return Enumerable.Range(1, 5).Select(Function(index) New WeatherForecast With {
				.Date = DateTime.Now.AddDays(index),
				.TemperatureC = Random.Shared.Next(-20, 55),
				.Summary = Summaries(Random.Shared.Next(Summaries.Length))
			}).ToArray()
		End Function
	End Class
End Namespace
$vbLabelText   $csharpLabel

Neste exemplo, os atributos SwaggerOperation e SwaggerResponse são usados ​​para fornecer descrições OpenAPI detalhadas e códigos de resposta para o endpoint.

Saída

OpenAPI .NET (Como funciona para desenvolvedores): Figura 1 - Saída de anotações personalizadas

Clique no botão Executar e você receberá a seguinte resposta.

OpenAPI .NET (Como funciona para desenvolvedores): Figura 2 - Saída de resposta

IronPDF

IronPDF para ASP.NET é uma ferramenta poderosa que permite a geração e manipulação perfeitas de documentos PDF em aplicações ASP.NET . Com sua API intuitiva e funcionalidade robusta, os desenvolvedores podem integrar facilmente a geração de PDFs em seus projetos web, oferecendo aos usuários recursos aprimorados de gerenciamento de documentos. Seja para criar PDFs do zero, converter conteúdo HTML em PDF ou adicionar elementos dinâmicos como imagens e texto, o IronPDF simplifica o processo, garantindo a geração de documentos de forma eficiente e profissional.

Passos para instalar usando o Gerenciador de Pacotes NuGet :

  1. Abra seu projeto ASP.NET no Visual Studio e navegue até o menu "Ferramentas".
  2. Selecione "Gerenciador de Pacotes NuGet " e clique em "Gerenciar Pacotes NuGet para a Solução".
  3. Na aba "Procurar", pesquise por "IronPDF" e selecione a versão desejada. Clique em "Instalar" para adicionar o pacote ao seu projeto. O IronPDF e suas dependências serão baixados e integrados automaticamente, permitindo que você comece a aproveitar suas funcionalidades em sua aplicação ASP.NET sem problemas.

OpenAPI .NET (Como funciona para desenvolvedores): Figura 3 - IronPDF

Obter arquivo PDF em resposta a uma chamada de API

Adicione o seguinte código ao seu arquivo de controlador; ele usa o IronPDF para criar um arquivo PDF e retorná-lo como resposta à chamada da API.

using Microsoft.AspNetCore.Mvc;
using IronPdf;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        public IActionResult GetWeatherForecastPdf()
        {
            var htmlContent = @"
        <html>
        <head>
            <title>Weather Forecast</title>
        </head>
        <body>
            <h1>Weather Forecast</h1>
            <table>
                <tr>
                    <th>Date</th>
                    <th>Temperature (Celsius)</th>
                    <th>Summary</th>
                </tr>";

            var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            });

            // Iterate over the forecasts and add data to the HTML string
            foreach (var forecast in forecasts)
            {
                htmlContent += $@"
            <tr>
                <td>{forecast.Date.ToShortDateString()}</td>
                <td>{forecast.TemperatureC}</td>
                <td>{forecast.Summary}</td>
            </tr>";
            }

            htmlContent += @"
            </table>
        </body>
        </html>";

            // Convert the HTML string to a PDF using IronPDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Retrieve the byte array of the generated PDF
            var pdfBytes = pdfDocument.BinaryData;
            // Return the PDF file to the client
            return File(pdfBytes, "application/pdf", "WeatherForecast.pdf");
        }
    }
}
using Microsoft.AspNetCore.Mvc;
using IronPdf;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        public IActionResult GetWeatherForecastPdf()
        {
            var htmlContent = @"
        <html>
        <head>
            <title>Weather Forecast</title>
        </head>
        <body>
            <h1>Weather Forecast</h1>
            <table>
                <tr>
                    <th>Date</th>
                    <th>Temperature (Celsius)</th>
                    <th>Summary</th>
                </tr>";

            var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            });

            // Iterate over the forecasts and add data to the HTML string
            foreach (var forecast in forecasts)
            {
                htmlContent += $@"
            <tr>
                <td>{forecast.Date.ToShortDateString()}</td>
                <td>{forecast.TemperatureC}</td>
                <td>{forecast.Summary}</td>
            </tr>";
            }

            htmlContent += @"
            </table>
        </body>
        </html>";

            // Convert the HTML string to a PDF using IronPDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Retrieve the byte array of the generated PDF
            var pdfBytes = pdfDocument.BinaryData;
            // Return the PDF file to the client
            return File(pdfBytes, "application/pdf", "WeatherForecast.pdf");
        }
    }
}
Imports Microsoft.AspNetCore.Mvc
Imports IronPdf

Namespace WebApplication8.Controllers
	<ApiController>
	<Route("[controller]")>
	Public Class WeatherForecastController
		Inherits ControllerBase

		Private Shared ReadOnly Summaries() As String = { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }

		Private ReadOnly _logger As ILogger(Of WeatherForecastController)

		Public Sub New(ByVal logger As ILogger(Of WeatherForecastController))
			_logger = logger
		End Sub

		<HttpGet(Name := "GetWeatherForecast")>
		Public Function GetWeatherForecastPdf() As IActionResult
			Dim htmlContent = "
        <html>
        <head>
            <title>Weather Forecast</title>
        </head>
        <body>
            <h1>Weather Forecast</h1>
            <table>
                <tr>
                    <th>Date</th>
                    <th>Temperature (Celsius)</th>
                    <th>Summary</th>
                </tr>"

			Dim forecasts = Enumerable.Range(1, 5).Select(Function(index) New WeatherForecast With {
				.Date = DateTime.Now.AddDays(index),
				.TemperatureC = Random.Shared.Next(-20, 55),
				.Summary = Summaries(Random.Shared.Next(Summaries.Length))
			})

			' Iterate over the forecasts and add data to the HTML string
			For Each forecast In forecasts
				htmlContent &= $"
            <tr>
                <td>{forecast.Date.ToShortDateString()}</td>
                <td>{forecast.TemperatureC}</td>
                <td>{forecast.Summary}</td>
            </tr>"
			Next forecast

			htmlContent &= "
            </table>
        </body>
        </html>"

			' Convert the HTML string to a PDF using IronPDF
			Dim renderer = New ChromePdfRenderer()
			Dim pdfDocument = renderer.RenderHtmlAsPdf(htmlContent)

			' Retrieve the byte array of the generated PDF
			Dim pdfBytes = pdfDocument.BinaryData
			' Return the PDF file to the client
			Return File(pdfBytes, "application/pdf", "WeatherForecast.pdf")
		End Function
	End Class
End Namespace
$vbLabelText   $csharpLabel

OpenAPI .NET (Como funciona para desenvolvedores): Figura 4 - Saída da API

Faça o download e abra o arquivo PDF em anexo.

OpenAPI .NET (Como funciona para desenvolvedores): Figura 5 - Saída em PDF

Conclusão

O OpenAPI, anteriormente conhecido como Swagger, simplifica o design e a documentação de APIs RESTful no ecossistema .NET por meio de bibliotecas como o Swashbuckle, facilitando a geração automática de documentação de API para projetos ASP.NET Core . Demonstrando a sinergia entre OpenAPI e IronPDF, mostramos como utilizar os recursos do IronPDF para gerar arquivos PDF a partir de conteúdo HTML e retorná-los como respostas de API, enriquecendo a funcionalidade de aplicativos ASP.NET . Ao adotar os padrões OpenAPI e aproveitar os recursos robustos do IronPDF, os desenvolvedores podem aprimorar suas práticas de documentação de API e entregar aos usuários aplicativos refinados e repletos de funcionalidades.

Para obter informações detalhadas sobre o licenciamento do IronPDF , consulte os detalhes de licenciamento do IronPDF . Além disso, você pode consultar nosso tutorial de conversão de HTML para PDF para obter mais orientações.

Perguntas frequentes

Como posso converter conteúdo HTML em PDF em uma aplicação ASP.NET?

Você pode usar o IronPDF em uma aplicação ASP.NET para converter conteúdo HTML em PDF. Ao aproveitar os recursos do IronPDF, você pode renderizar strings ou arquivos HTML em documentos PDF, que podem então ser fornecidos como respostas de API ou salvos para fins de gerenciamento de documentos.

Qual é o papel do OpenAPI no ecossistema .NET?

O OpenAPI desempenha um papel crucial no ecossistema .NET, fornecendo uma maneira padronizada de definir e documentar APIs RESTful. Essa integração é frequentemente facilitada por ferramentas como o Swashbuckle, que ajuda a gerar especificações OpenAPI e permite o consumo fácil de APIs em projetos ASP.NET Core.

Como faço para configurar a interface do usuário Swagger em um projeto .NET usando o Swashbuckle?

Para configurar a interface do usuário Swagger em um projeto .NET usando o Swashbuckle, instale o pacote Swashbuckle.AspNetCore via NuGet. Em seguida, configure os serviços Swagger no seu arquivo Program.cs e configure o middleware Swagger para habilitar a geração automática e o acesso à documentação da API por meio da interface do usuário Swagger.

Como posso gerar SDKs de cliente a partir de definições OpenAPI em .NET?

As definições OpenAPI podem ser usadas para gerar SDKs de cliente, que facilitam o consumo de APIs ao abstrair a complexidade das chamadas de API. No .NET, ferramentas como o Swashbuckle podem gerar essas definições, que podem então ser usadas com ferramentas como o AutoRest para criar SDKs de cliente em várias linguagens de programação.

Quais são as vantagens de usar anotações personalizadas na documentação OpenAPI?

As anotações personalizadas na documentação OpenAPI aprimoram a clareza e o detalhamento das especificações da API. No .NET, o Swashbuckle permite usar atributos como SwaggerOperation e SwaggerResponse para adicionar descrições e códigos de resposta, tornando a documentação da API mais informativa e fácil de entender para os desenvolvedores.

Como posso enviar um arquivo PDF como resposta de uma API no ASP.NET Core?

É possível fornecer um arquivo PDF como resposta de uma API no ASP.NET Core usando o IronPDF. Gere o PDF a partir do conteúdo HTML utilizando os métodos de renderização do IronPDF e retorne o arquivo PDF na ação do seu controlador de API usando IActionResult do ASP.NET Core para incluir o arquivo na resposta.

Quais são os benefícios da combinação de OpenAPI e ferramentas de geração de PDF para aplicações ASP.NET?

A combinação de OpenAPI e ferramentas de geração de PDF, como o IronPDF, em aplicações ASP.NET proporciona uma documentação de API abrangente e aprimora a funcionalidade, permitindo que as APIs retornem documentos PDF profissionais. Essa integração oferece suporte ao gerenciamento eficiente de documentos e enriquece os recursos gerais da aplicação.

Curtis Chau
Curtis Chau
  Converse agora mesmo com a equipe de engenharia.
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...

Leia mais

Artigos relacionados

Teste grátis por 30 dias → Produto completo. Sem limites. Sem cartão. Teste gratuito

Equipe de suporte de ferro

Estamos online 24 horas por dia, 5 dias por semana.
Bater papo
E-mail
Liga para mim