참고 항목
이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.
중요합니다
이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.
현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.
ASP.NET Core는 컨트롤러 기반 및 최소 API 앱에서 OpenAPI 문서 생성을 지원합니다. OpenAPI 사양은 HTTP API를 문서화하기 위한 프로그래밍 언어 독립적 표준입니다. 이 표준은 기본 제공 API와 오픈 소스 라이브러리의 조합을 통해 ASP.NET Core 앱에서 지원됩니다. 애플리케이션에서 OpenAPI 통합에는 다음과 같은 세 가지 주요 측면이 있습니다.
- 앱의 엔드포인트에 대한 정보 생성.
- OpenAPI 스키마와 일치하는 형식으로 정보 수집.
- 시각적 UI 또는 직렬화된 파일을 통해 생성된 OpenAPI 문서를 노출합니다.
ASP.NET Core 앱은 패키지를 통해 Microsoft.AspNetCore.OpenApi
앱의 엔드포인트에 대한 정보를 생성하기 위한 기본 제공 지원을 제공합니다.
다음 코드는 ASP.NET Core 최소 웹 API 템플릿에서 생성되며 OpenAPI를 사용합니다.
using Microsoft.AspNetCore.OpenApi;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}
app.UseHttpsRedirection();
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateTime.Now.AddDays(index),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
})
.WithName("GetWeatherForecast");
app.Run();
internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
앞의 강조 표시된 코드에서 다음을 수행합니다.
-
AddOpenApi
는 OpenAPI 문서 생성에 필요한 서비스를 애플리케이션의 DI 컨테이너에 등록합니다. -
MapOpenApi
는 JSON으로 직렬화된 OpenAPI 문서를 보기 위해 애플리케이션에 엔드포인트를 추가합니다. OpenAPI 엔드포인트는 중요한 정보를 노출하는 위험을 최소화하고 프로덕션의 취약성을 줄이기 위해 개발 환경으로 제한됩니다.
Microsoft.AspNetCore.OpenApi
NuGet 패키지
패키지는 Microsoft.AspNetCore.OpenApi
다음과 같은 기능을 제공합니다.
- 런타임에 OpenAPI 문서를 생성하고 애플리케이션의 엔드포인트를 통해 액세스할 수 있도록 지원합니다.
- 생성된 문서를 수정할 수 있는 "변환기" API를 지원합니다.
패키지를 사용 Microsoft.AspNetCore.OpenApi
하려면 프로젝트 파일에 PackageReference로 추가합니다.
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<PropertyGroup>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
<PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
</ItemGroup>
</Project>
패키지에 대한 Microsoft.AspNetCore.OpenApi
자세한 내용은 OpenAPI 문서 생성을 참조 하세요.
Microsoft.Extensions.ApiDescription.Server
NuGet 패키지
패키지는 Microsoft.Extensions.ApiDescription.Server
빌드 시 OpenAPI 문서를 생성하고 직렬화할 수 있도록 지원합니다.
사용 Microsoft.Extensions.ApiDescription.Server
하려면 프로젝트 파일에 PackageReference로 추가합니다.
빌드 시 문서 생성은 속성을 설정하여 사용하도록 설정됩니다 OpenApiGenerateDocuments
.
기본적으로 생성된 OpenAPI 문서는 디렉터리에 저장 obj
되지만 속성을 설정 OpenApiDocumentsDirectory
하여 출력 디렉터리를 사용자 지정할 수 있습니다.
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<PropertyGroup>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
<PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
</ItemGroup>
</Project>
API v. API 작업 버전 API 엔드포인트
다음 섹션에서는 ASP.NET Core 및 OpenAPI 설명서의 컨텍스트에서 API, API 엔드포인트 및 API 작업 간의 차이점을 설명합니다.
API(애플리케이션 프로그래밍 인터페이스)
API는 소프트웨어 애플리케이션을 빌드하고 상호 작용하기 위한 규칙 및 프로토콜 집합입니다. 다양한 소프트웨어 구성 요소가 통신하는 방법을 정의합니다. 일반적인 웹 개발에서 "API"는 일반적으로 HTTP를 통해 기능을 노출하는 웹 서비스를 나타냅니다.
ASP.NET Core에서 API는 일반적으로 들어오는 HTTP 요청을 처리하고 응답을 반환하는 최소 API 또는 컨트롤러를 사용하여 빌드됩니다.
ASP.NET Core의 내부 명명 규칙은 때때로 "API"를 다르게 사용합니다. 예를 들어 API 탐색기에서 "ApiDescription"은 실제로 전체 API 서비스가 아닌 API 작업을 나타냅니다. 이러한 구분은 내부 명명 규칙을 반영하며 여기서 사용되는 광범위한 정의와 다를 수 있습니다.
API 탐색기에 대한 자세한 내용은 ASP.NET Core의 ApiExplorer 소개 를 참조하세요.
API 작업
API 작업은 API가 제공하는 특정 작업 또는 기능을 나타냅니다. ASP.NET Core에서는 다음과 같습니다.
- MVC 스타일 API의 컨트롤러 작업 메서드
- 최소 API의 경로 처리기
각 작업은 HTTP 메서드(GET
, , POST
등), 경로, PUT
매개 변수 및 응답에 의해 정의됩니다.
API 엔드포인트
API 엔드포인트는 특정 URL입니다.
- 이는 API에서 노출하는 특정 리소스 또는 기능을 나타냅니다.
- 특정 API 작업과 상호 작용하기 위해 클라이언트가 HTTP 요청을 보내야 하는 정확한 주소를 제공합니다.
엔드포인트는 지원되는 HTTP 메서드와 함께 API의 기본 URL과 원하는 리소스에 대한 특정 경로의 조합입니다.
- 컨트롤러 기반 API의 경우 엔드포인트는 경로 템플릿을 컨트롤러 및 작업과 결합합니다.
- 최소 API의 경우 엔드포인트는 등으로
app.MapGet()
app.MapPost()
명시적으로 정의됩니다.
예를 들어 api/products/{id}
다음 작업을 지원하는 엔드포인트입니다.
GET /api/products/{id}
PUT /api/products/{id}
PATCH /api/products/{id}
Delete /api/products/{id}
HEAD /api/products/{id}
엔드포인트에는 쿼리 매개 변수가 포함되는 경우가 많습니다. 예를 들면 다음과 같습니다. GET /api/products?category=electronics&sort=price
OpenAPI 설명서
OpenAPI의 컨텍스트에서 설명서는 모든 엔드포인트 및 작업을 포함하여 API 전체를 설명합니다. OpenAPI는 API를 문서화하는 구조화된 방법을 제공하므로 개발자가 API와 상호 작용하는 방법을 더 쉽게 이해할 수 있습니다.
API 작업은 OpenAPI 설명서의 주요 초점입니다. OpenAPI 사양은 경로(엔드포인트)로 그룹화된 작업별로 설명서를 구성합니다. 각 작업은 매개 변수, 요청 본문, 응답 등의 세부 정보로 설명됩니다. 이 구조화된 형식을 사용하면 도구에서 클라이언트 라이브러리, 서버 스텁 및 대화형 설명서를 자동으로 생성할 수 있습니다.
OpenAPI 문서에서 다음을 수행합니다.
- 전체 문서에서는 API 전체를 설명합니다.
- 각 경로 항목(예:
/api/products/{id}
)은 엔드포인트를 나타냅니다. - 각 경로에서 HTTP 메서드(
GET
,POST
,PUT
등)는 작업을 정의합니다. - 각 작업에는 매개 변수, 요청 본문, 응답 등에 대한 세부 정보가 포함됩니다.
OpenAPI JSON 형식의 예:
json{
"paths": {
"/api/products/{id}": { // This is the endpoint
"get": { // This is the operation
"summary": "Get a product by ID",
"parameters": [...],
"responses": {...}
},
"put": { // Another operation on the same endpoint
"summary": "Update a product",
"parameters": [...],
"responses": {...}
}
}
}
}
API, API 작업 및 API 엔드포인트 비교
다음 표에는 API, API 작업 및 API 엔드포인트 간의 차이점이 요약되어 있습니다.
개념 | API 작업 | API 엔드포인트 |
---|---|---|
정의 | API 작업에 대한 논리적 설명: 메서드 + 경로 + 동작 | 요청을 수신 대기하는 실제 구성된 HTTP 경로 |
수준 | 개념적, 발생할 수 있는 작업 | 어떤 URL과 메서드가 구체적으로 일치하는지 |
에 연결 | OpenAPI API 디자인/사양 | ASP.NET Core의 런타임 라우팅 |
설명 | API가 수행하는 작업(예: "제품 만들기") | 호출 위치 및 방법(예: POST https://localhost:7099/api/products POST https://contoso.com/api/products |
ASP.NET Core에서 | 라우팅이 확인되기 전에 컨트롤러 작업 또는 최소 API 메서드 | 런타임에 결정되는 엔드포인트 개체 |
GitHub의 ASP.NET Core OpenAPI 소스 코드
추가 리소스
OpenAPI 사양은 HTTP API를 문서화하기 위한 프로그래밍 언어 독립적 표준입니다. 이 표준은 기본 제공 API와 오픈 소스 라이브러리의 조합을 통해 최소 API에서 지원됩니다. 애플리케이션에서 OpenAPI 통합에는 다음과 같은 세 가지 주요 측면이 있습니다.
- 앱의 엔드포인트에 대한 정보 생성.
- OpenAPI 스키마와 일치하는 형식으로 정보 수집.
- 시각적 UI 또는 직렬화된 파일을 통해 생성된 OpenAPI 스키마 노출.
최소 API는 Microsoft.AspNetCore.OpenApi
패키지를 통해 앱의 엔드포인트에 대한 정보를 생성하기 위한 기본 제공 지원을 제공합니다. 시각적 UI를 통해 생성된 OpenAPI 정의를 노출하려면 타사 패키지가 필요합니다.
컨트롤러 기반 API에서 OpenAPI 지원에 대한 자세한 내용은 이 문서의 .NET 9 버전을 참조 하세요.
ASP.NET Core