Dukungan OpenAPI di aplikasi ASP.NET Core API

ASP.NET Core mendukung pembuatan dokumen OpenAPI di aplikasi API berbasis pengontrol dan minimal. Spesifikasi OpenAPI adalah standar bahasa-agnostik pemrograman untuk mendokumen API HTTP. Standar ini didukung di aplikasi ASP.NET Core melalui kombinasi API bawaan dan pustaka sumber terbuka. Ada tiga aspek utama untuk integrasi OpenAPI dalam aplikasi:

• Menghasilkan informasi tentang titik akhir di aplikasi.
• Mengumpulkan informasi ke dalam format yang cocok dengan skema OpenAPI.
• Mengekspos dokumen OpenAPI yang dihasilkan melalui UI visual atau file berseri.

ASP.NET Core menyediakan dukungan bawaan untuk menghasilkan informasi tentang titik akhir di aplikasi melalui Microsoft.AspNetCore.OpenApi paket.

Kode berikut dihasilkan oleh templat API web minimal ASP.NET Core dan menggunakan 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);
}

Dalam kode yang disorot sebelumnya:

• AddOpenApi mendaftarkan layanan yang diperlukan untuk pembuatan dokumen OpenAPI ke dalam kontainer DI aplikasi.
• MapOpenApi menambahkan titik akhir ke dalam aplikasi untuk melihat dokumen OpenAPI yang diserialisasikan ke JSON. Titik akhir OpenAPI dibatasi untuk lingkungan pengembangan untuk meminimalkan risiko mengekspos informasi sensitif dan mengurangi kerentanan dalam produksi.

Microsoft.AspNetCore.OpenApi Paket NuGet

Paket ini Microsoft.AspNetCore.OpenApi menyediakan fitur-fitur berikut:

• Dukungan untuk menghasilkan dokumen OpenAPI pada waktu proses dan mengaksesnya melalui titik akhir pada aplikasi.
• Dukungan untuk API "transformer" yang memungkinkan modifikasi dokumen yang dihasilkan.

Untuk menggunakan Microsoft.AspNetCore.OpenApi paket, tambahkan sebagai PackageReference ke file proyek:

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

Untuk mempelajari selengkapnya tentang Microsoft.AspNetCore.OpenApi paket, lihat Membuat dokumen OpenAPI.

Microsoft.Extensions.ApiDescription.Server Paket NuGet

Paket ini Microsoft.Extensions.ApiDescription.Server menyediakan dukungan untuk menghasilkan dokumen OpenAPI pada waktu build dan menserialisasikannya.

Untuk menggunakan Microsoft.Extensions.ApiDescription.Server, tambahkan sebagai PackageReference ke file proyek. Pembuatan dokumen pada waktu build diaktifkan dengan mengatur OpenApiGenerateDocuments properti . Secara default, dokumen OpenAPI yang dihasilkan disimpan ke obj direktori, tetapi Anda dapat menyesuaikan direktori output dengan mengatur OpenApiDocumentsDirectory properti .

<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. Operasi API v. Titik akhir API

Bagian berikut menjelaskan perbedaan antara API, titik akhir API, dan operasi API dalam konteks dokumentasi ASP.NET Core dan OpenAPI.

API (Antarmuka Pemrograman Aplikasi)

API adalah seperangkat aturan dan protokol untuk membangun dan berinteraksi dengan aplikasi perangkat lunak. Ini mendefinisikan bagaimana komponen perangkat lunak yang berbeda harus berkomunikasi. Dalam pengembangan web umum, "API" biasanya mengacu pada layanan web yang mengekspos fungsionalitas melalui HTTP.

Di ASP.NET Core, API biasanya dibangun menggunakan pengontrol atau API minimal, yang menangani permintaan HTTP masuk dan mengembalikan respons.

Konvensi penamaan internal ASP.NET Core terkadang menggunakan "API" dengan cara yang berbeda. Misalnya, di API Explorer, "ApiDescription" sebenarnya mewakili Operasi API daripada layanan API lengkap. Perbedaan ini mencerminkan konvensi penamaan internal dan terkadang berbeda dari definisi yang lebih luas yang digunakan di sini.

Lihat Pengenalan ApiExplorer di ASP.NET Core untuk informasi selengkapnya tentang API Explorer.

Operasi API

Operasi API mewakili tindakan atau kemampuan tertentu yang disediakan API. Dalam ASP.NET Core, ini sesuai dengan:

• Metode tindakan pengontrol dalam API bergaya MVC
• Penangan rute di API Minimal

Setiap operasi didefinisikan oleh metode HTTP-nya (GET, , POST, PUTdll.), jalur, parameter, dan respons.

Titik Akhir API

Titik akhir API adalah URL tertentu:

• Itu mewakili sumber daya atau fungsionalitas tertentu yang diekspos oleh API.
• Menyediakan alamat yang tepat yang perlu dikirimi klien permintaan HTTP untuk berinteraksi dengan operasi API tertentu.

Titik akhir adalah kombinasi URL dasar API dan jalur tertentu ke sumber daya yang diinginkan, bersama dengan metode HTTP yang didukung:

• Untuk API berbasis pengontrol, titik akhir menggabungkan templat rute dengan pengontrol dan tindakan.
• Untuk API Minimal, titik akhir secara eksplisit didefinisikan dengan app.MapGet(), app.MapPost(), dll.

Misalnya, endpoint api/products/{id} yang mendukung operasi berikut:

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

Titik akhir sering menyertakan parameter kueri, misalnya, GET /api/products?category=electronics&sort=price

Dokumentasi OpenAPI

Dalam konteks OpenAPI, dokumentasi menjelaskan API secara keseluruhan, termasuk semua titik akhir dan operasinya. OpenAPI menyediakan cara terstruktur untuk mendokumen API, sehingga pengembang lebih mudah memahami cara berinteraksi dengannya.

Operasi API adalah fokus utama dokumentasi OpenAPI. Spesifikasi OpenAPI mengatur dokumentasi menurut operasi, yang dikelompokkan menurut jalur (titik akhir). Setiap operasi dijelaskan dengan detail seperti parameter, badan permintaan, respons, dan banyak lagi. Format terstruktur ini memungkinkan alat untuk menghasilkan pustaka klien, stub server, dan dokumentasi interaktif secara otomatis.

Dalam dokumen OpenAPI:

• Seluruh dokumen menjelaskan API secara keseluruhan
• Setiap item jalur (seperti /api/products/{id}) mewakili titik akhir
• Di bawah setiap jalur, metode HTTP (GET, , POST, PUTdll.) menentukan operasi
• Setiap operasi berisi detail tentang parameter, isi permintaan, respons, dll.

Contoh dalam format 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, operasi API, dan perbandingan titik akhir API

Tabel berikut ini meringkas perbedaan antara API, operasi API, dan titik akhir API:

Konsep	Operasi API	Titik Akhir API
Definisi	Deskripsi logis dari tindakan API: metode + jalur + perilaku	Rute HTTP yang sebenarnya dikonfigurasi untuk mendengarkan permintaan
Tingkat	Secara konseptual, tindakan apa yang mungkin terjadi?	Secara spesifik, URL dan metode apa yang sesuai
Terikat dengan	Desain/spesifikasi OPENAPI API	Routing ASP.NET Core pada waktu eksekusi
Menjelaskan	Apa yang dilakukan API misalnya, "buat produk"	Di mana dan cara memanggilnya, misalnya, , POST https://localhost:7099/api/productsPOST https://contoso.com/api/products
Dalam ASP.NET Core	Tindakan pengontrol atau metode API Minimal, sebelum perutean diselesaikan	Objek titik akhir ditentukan pada runtime

ASP.NET kode sumber Core OpenAPI di GitHub

• TambahkanOpenApi
• OpenApiDocumentService
• OpenApiOptions

Sumber Tambahan

• Autentikasi dan otorisasi dalam API minimal