API Documentation with OpenAPI

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Describe your API in an OpenAPI document, serve it from ASP.NET Core, and use it to list endpoints, lint the design, contract-test responses and generate clients.

OpenAPI is a standard format for describing an API in a single JSON or YAML file. It acts as a complete guide to the API by listing its endpoints, request formats, response formats, status codes, and data models. Both developers and software tools can read the same file to understand how the API works.

Because everything is written in one place, OpenAPI makes APIs easier to document, share, test, and use. Instead of guessing how an API works, developers can read the OpenAPI document and start building immediately.

Watch a Partner Guess

A delivery partner wants to connect to the Brew & Bytes API. Unfortunately, there is no documentation. They try:

• GET /order/101
• GET /orders?id=101

Neither works. Finally, they email the team and wait for a response. Two days are lost. Now the API publishes an OpenAPI document at:

/openapi/v1.json

Press Run.

The response contains the complete API description, including:

• Paths
• HTTP methods
• Status codes
• Request bodies
• Response bodies
• Object structures

The partner can read the document and start integrating with the API immediately.

In simple words: an OpenAPI document is the API contract written in a format that both people and software tools can understand.

TL;DR

• An OpenAPI document describes an API in a standard format.
• It lists endpoints, methods, request bodies, responses, status codes, and object structures.
• info contains details about the API.
• paths contains the API endpoints.
• components.schemas describes the data models.
• ASP.NET Core can generate the document automatically using AddOpenApi() and MapOpenApi().
• Tools use it to create documentation, generate client code, run tests, and check API design.
• The document should always match the actual API code.

A Real-World Example

Think about a restaurant menu. Customers do not enter the kitchen to see what food is available. Instead, they read the menu. The menu tells them:

• What dishes are available.
• What each dish contains.
• How much each dish costs.

Everyone uses the same menu:

• Customers
• Waiters
• Cashiers

An OpenAPI document serves the same purpose for an API. It tells developers everything they need to know about the API without looking at the server code.

What You Will Learn

In this lesson, you will learn:

1. What information an OpenAPI document contains.
2. How ASP.NET Core generates and serves an OpenAPI document.
3. How programs can read the document.
4. How to validate and test an API using the document.
5. How client code can be generated automatically.

Serve the Document

The example above serves a manually written OpenAPI document so that you can easily see each part. In a real ASP.NET Core application, the framework can generate the document automatically.

// Program.cs (requires Microsoft.AspNetCore.OpenApi)

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi(); // Serves /openapi/v1.json

app.MapGet("/menu", () => menu)
   .WithSummary("List the menu")
   .Produces<List<MenuItem>>(200);

This code automatically generates an OpenAPI document based on the API endpoints. The generated document contains the same information as the manually written example.

Read the Document with Code

An OpenAPI document is simply JSON. Because it is JSON, any application can read and process it. The example below reads the document and lists all operations, summaries, and response codes.

This is exactly how tools such as Swagger UI and Scalar work. They read the OpenAPI document and automatically create a documentation website.

Validate the Design

A linter checks whether the OpenAPI document follows your API design standards. For example, it can verify:

• Every endpoint has a summary.
• Error responses are documented.
• Required information is not missing.

In this example, GET /menu documents only a 200 response. It does not explain what happens when an error occurs. The linter reports the issue so it can be fixed before users discover it.

Contract Tests

A contract test checks whether the actual API responses match the OpenAPI document. If the API returns something different from what the document describes, the test fails.

In this example:

• Response A matches the OpenAPI contract.
• Response B is missing the quantity field.
• Response B sends total as text instead of a number.

The test catches these problems before they reach API consumers.

Generate a Client

Because an OpenAPI document precisely describes the API, tools can automatically generate client code. The following example creates method signatures from the OpenAPI document.

Full client generators such as:

• NSwag
• Kiota
• openapi-typescript

can generate:

• Models
• Classes
• HTTP requests
• JSON serialization code

This saves time and reduces manual coding.

Where You See This

• Public APIs publish OpenAPI documents for developers.
• Documentation websites such as Swagger UI are built from OpenAPI documents.
• API gateways can import OpenAPI documents to create routes.
• Development teams often review the OpenAPI design before writing any code.
• Client generators use OpenAPI documents to create SDKs automatically.

Common mistakes

Exercises

What to Remember

• An OpenAPI document describes every path, method, response and schema.
• ASP.NET Core generates it with AddOpenApi() and serves it with MapOpenApi().
• Docs pages, client generators, linters and contract tests all read it.
• Keep it true: generate it from code, and test it on every build.

Next: API Versioning. You will change the API without breaking the partners who use it.