Back to Details

aspnet-minimal-api-openapi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ASP.NET Minimal API with OpenAPI

带OpenAPI文档的ASP.NET Minimal API

Your goal is to help me create well-structured ASP.NET Minimal API endpoints with correct types and comprehensive OpenAPI/Swagger documentation.

你的目标是协助我创建结构清晰、类型规范且具备完整OpenAPI/Swagger文档的ASP.NET Minimal API端点。

API Organization

API 组织架构

Group related endpoints using
```
MapGroup()
```
extension
Use endpoint filters for cross-cutting concerns
Structure larger APIs with separate endpoint classes
Consider using a feature-based folder structure for complex APIs

使用
```
MapGroup()
```
扩展方法对相关端点进行分组
为横切关注点使用端点过滤器
为大型API使用独立的端点类进行架构设计
对于复杂API，考虑采用基于功能的文件夹结构

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 that align with API design standards
Apply
```
[Required]
```
and other validation attributes to enforce constraints
Use the ProblemDetailsService and StatusCodePages to get standard error responses

定义明确的请求和响应DTO/模型
创建带有合适验证特性的清晰模型类
为不可变的请求/响应对象使用record类型
使用符合API设计标准的有意义属性名称
应用
```
[Required]
```
及其他验证特性来强制约束
使用ProblemDetailsService和StatusCodePages获取标准化错误响应

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 C# 10+ features like nullable annotations and init-only properties

使用带有显式类型绑定的强类型路由参数
使用
```
Results<T1, T2>
```
表示多种响应类型
对于强类型响应，返回
```
TypedResults
```
而非
```
Results
```
利用C# 10+特性，如可空注解和仅初始化属性

OpenAPI Documentation

OpenAPI 文档

Use the built-in OpenAPI document support added in .NET 9
Define operation summary and description
Add operationIds 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 elements like servers, tags, and security schemes
Use schema transformers to apply customizations to OpenAPI schemas

使用.NET 9中新增的内置OpenAPI文档支持
定义操作摘要和描述
使用
```
WithName
```
扩展方法添加operationId
使用
```
[Description()]
```
为属性和参数添加描述
为请求和响应设置合适的内容类型
使用文档转换器添加服务器、标签和安全方案等元素
使用架构转换器对OpenAPI架构进行自定义配置