Aspnet Minimal Api Openapi

API Organization

• Group related endpoints using MapGroup() extension.
• Use endpoint filters for cross-cutting concerns.
• Structure larger APIs with separate endpoint classes.
• Use feature-based folders for complex APIs.

Request and Response Types

• Define explicit request and response DTOs/models.
• Create clear model classes with proper validation attributes.
• Use record types for immutable request/response objects.
• Use meaningful property names aligned with API design standards.
• Apply [Required] and other validation attributes to enforce constraints.
• Use ProblemDetails service and status code pages for standard error responses.

Type Handling

• Use strongly typed route parameters with explicit type binding.
• Use Results<T1, T2> to represent multiple response types.
• Return TypedResults instead of Results for strongly typed responses.
• Leverage modern C# features like nullable annotations and init-only properties.

OpenAPI Documentation

• Use built-in OpenAPI document support added in .NET 9+.
• Define operation summary and description.
• Add operation IDs using the WithName extension method.
• Add descriptions to properties and parameters with [Description()].
• Set proper content types for requests and responses.
• Use document transformers to add servers, tags, and security schemes.
• Use schema transformers to apply customizations to OpenAPI schemas.

Quality Checks

• Endpoints are grouped by feature with clear route prefixes.
• Contracts are explicit and version-tolerant.
• Response types are strongly typed and exhaustive.
• OpenAPI shows meaningful operation names, descriptions, and schema details.
• Error responses are consistent and standardized.