What is OpenAPI in the context of .NET?

OpenAPI, also known as Swagger, is a specification for building and describing RESTful APIs. In the .NET ecosystem, OpenAPI integration is facilitated through libraries like Swashbuckle, which helps generate API documentation for ASP.NET Core projects.

How can I set up OpenAPI in a .NET project?

To set up OpenAPI in a .NET project, you can use the Swashbuckle library. Install it via NuGet Package Manager or the .NET CLI, and configure it in your ASP.NET Core project by updating the Program.cs file to add Swagger services and middleware.

What is IronPDF, and how does it relate to OpenAPI?

IronPDF is a powerful tool for generating and manipulating PDF documents in ASP.NET applications. It can be integrated with OpenAPI to create PDF files from HTML content and return them as API call responses, enhancing document management capabilities.

Can IronPDF convert HTML content to a PDF in an ASP.NET application?

Yes, IronPDF can convert HTML content to PDF in an ASP.NET application. It uses a Chrome-based renderer to transform HTML strings into PDF documents, which can then be returned as part of an API response.

How can you return a PDF file as an API response using IronPDF?

In your ASP.NET controller, first use IronPDF to convert HTML content into a PDF. Then, retrieve the PDF's byte array and return it as a file response to the API call using ASP.NET's IActionResult.

What are custom annotations in OpenAPI, and how are they used?

Custom annotations in OpenAPI, facilitated by Swashbuckle, allow developers to enrich their API documentation with additional information about endpoints. These annotations, such as SwaggerOperation and SwaggerResponse, provide detailed descriptions and response codes.

Is it possible to enhance OpenAPI documentation with custom annotations using Swashbuckle?

Yes, Swashbuckle allows developers to enhance OpenAPI documentation with custom annotations. These annotations can be integrated directly into controllers and models to provide extra insights about the API's behavior and data structures.

The C# PDF Library

Q: How do you generate OpenAPI documentation using Swashbuckle?

After Swashbuckle is configured in your ASP.NET Core project, running the application will automatically generate OpenAPI documentation. You can view this documentation through the Swagger UI interface by navigating to your API's Swagger endpoint.

Explore IronPDF Start Free Trial

HTML to PDF

Online Demo See All Code Examples

using IronPdf;

// Disable local disk access or cross-origin requests
Installation.EnableWebSecurity = true;

// Instantiate Renderer
var renderer = new ChromePdfRenderer();

// Create a PDF from a HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

// Advanced Example with HTML Assets
// Load external html assets: Images, CSS and JavaScript.
// An optional BasePath 'C:\site\assets\' is set as the file location to load assets from
var myAdvancedPdf = renderer.RenderHtmlAsPdf("<img src='icons/iron.png'>", @"C:\site\assets\");
myAdvancedPdf.SaveAs("html-with-assets.pdf");

using IronPdf;

// Disable local disk access or cross-origin requests
Installation.EnableWebSecurity = true;

// Instantiate Renderer
var renderer = new ChromePdfRenderer();

// Create a PDF from a HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

// Advanced Example with HTML Assets
// Load external html assets: Images, CSS and JavaScript.
// An optional BasePath 'C:\site\assets\' is set as the file location to load assets from
var myAdvancedPdf = renderer.RenderHtmlAsPdf("<img src='icons/iron.png'>", @"C:\site\assets\");
myAdvancedPdf.SaveAs("html-with-assets.pdf");

PM >Install-Package IronPdf

Install-Package IronPdf

.NET HELP

OpenAPI .NET (How It Works For Developers)

Jacob Mellor

Updated: April 21, 2026

OpenAPI, formerly known as Swagger, is a specification for building and describing RESTful APIs. It allows developers to define the structure of their APIs in a standardized format, enabling various tools and services to understand and interact with the REST API effectively and provide feedback. In the .NET ecosystem, OpenAPI .NET integration is facilitated through several libraries and tools that make it easier to create, document, and consume APIs.

In this article, we will learn about OpenAPI support specifications and how to create a PDF file using IronPDF and return it as an API call response.

Setting Up OpenAPI in .NET

To get started with the OpenAPI .NET project, you typically use the Swashbuckle library, which generates OpenAPI specification or documentation for your ASP.NET Core APIs.

Step 1: Install Swashbuckle

First, you need to install the Swashbuckle.AspNetCore package via NuGet in Visual Studio. You can do this using the NuGet Package Manager Console:

PM > Install-Package Swashbuckle.AspNetCore

Install-Package Swashbuckle.AspNetCore

Or by using the .NET CLI:

dotnet add package Swashbuckle.AspNetCore

dotnet add package Swashbuckle.AspNetCore

SHELL

Step 2: Configure Swashbuckle

Next, you need to configure Swashbuckle in your ASP.NET Core project. This involves updating the Program.cs file to add Swagger services and configure the Swagger middleware.

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()

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()

Generating and Viewing API Documentation

Once Swashbuckle is configured, running your application will automatically generate OpenAPI documentation. You can view these OpenAPI descriptions by navigating to the Swagger UI interface.

Using OpenAPI Definitions

OpenAPI definitions are powerful tools that can be used for generating client SDKs, testing APIs, and ensuring consistency across different services. The OpenAPI specification defines a standard, language-agnostic interface to APIs, which allows both humans and computers to understand the capabilities of a service without access to the source code.

Extending OpenAPI with Custom Annotations

Swashbuckle allows you to enhance your OpenAPI documentation with custom annotations. These annotations can be added directly to your controllers and models to provide additional information about the API's behavior and data structures.

Example: Custom Annotations

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

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

In this example, the SwaggerOperation and SwaggerResponse attributes are used to provide detailed OpenAPI descriptions and response codes for the endpoint.

Output

OpenAPI .NET (How It Works For Developers): Figure 1 - Custom Annotations Output

Click on the Execute button, and you will get the following response.

OpenAPI .NET (How It Works For Developers): Figure 2 - Response Output

IronPDF

IronPDF for ASP.NET is a powerful tool that enables seamless generation and manipulation of PDF documents within ASP.NET applications. With its intuitive API and robust functionality, developers can effortlessly integrate PDF generation into their web projects, offering enhanced document management capabilities to users. Whether it's creating PDFs from scratch, converting HTML content to PDF, or adding dynamic elements like images and text, IronPDF simplifies the process, ensuring efficient and professional document generation.

Steps to install using NuGet Package Manager:

Open your ASP.NET project in Visual Studio and navigate to the "Tools" menu.
Select "NuGet Package Manager" and then click on "Manage NuGet Packages for Solution."
In the "Browse" tab, search for "IronPDF" and select the desired version. Click on "Install" to add the package to your project. IronPDF and its dependencies will be automatically downloaded and integrated, allowing you to start leveraging its functionality in your ASP.NET application seamlessly.

OpenAPI .NET (How It Works For Developers): Figure 3 - IronPDF

Get PDF File in Response to API Call

Add the following code to your controller file, it uses IronPDF to create a PDF file and return it as a response to the API call.

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

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

OpenAPI .NET (How It Works For Developers): Figure 4 - API Output

Download and open the attached PDF file.

OpenAPI .NET (How It Works For Developers): Figure 5 - PDF Output

Conclusion

OpenAPI, formerly known as Swagger, streamlines RESTful API design and documentation in the .NET ecosystem through libraries like Swashbuckle, facilitating automatic API documentation generation for ASP.NET Core projects. Demonstrating the synergy between OpenAPI and IronPDF, we showcased how to utilize IronPDF's capabilities to generate PDF files from HTML content and return them as API responses, enriching the functionality of ASP.NET applications. By embracing OpenAPI standards and leveraging IronPDF's robust features, developers can enhance their API documentation practices and deliver polished, feature-rich applications to users.

For detailed information on IronPDF licensing, please refer to the IronPDF licensing details. Additionally, you can explore our HTML to PDF conversion tutorial for further guidance.

Jacob Mellor

Chat with engineering team now

Chief Technology Officer

Jacob Mellor is Chief Technology Officer at Iron Software and a visionary engineer pioneering C# PDF technology. As the original developer behind Iron Software's core codebase, he has shaped the company's product architecture since its inception, transforming it alongside CEO Cameron Rimington into a 50+ person company serving NASA, Tesla, and global government agencies.

...