Menggunakan dokumen openAPI

Menggunakan UI Swagger untuk pengujian ad-hoc lokal

Secara default, Microsoft.AspNetCore.OpenApi paket tidak dikirim dengan dukungan bawaan untuk memvisualisasikan atau berinteraksi dengan dokumen OpenAPI. Alat populer untuk memvisualisasikan atau berinteraksi dengan dokumen OpenAPI termasuk UI Swagger dan ReDoc. UI Swagger dan ReDoc dapat diintegrasikan dalam aplikasi dalam beberapa cara. Editor seperti Visual Studio dan Visual Studio Code menawarkan ekstensi dan pengalaman bawaan untuk pengujian terhadap dokumen OpenAPI.

Paket ini Swashbuckle.AspNetCore.SwaggerUi menyediakan bundel aset web UI Swagger untuk digunakan dalam aplikasi. Paket ini dapat digunakan untuk merender UI untuk dokumen yang dihasilkan. Untuk mengonfigurasi ini:

• Pasang paket Swashbuckle.AspNetCore.SwaggerUi.
• Aktifkan middleware swagger-ui dengan referensi ke rute OpenAPI yang terdaftar sebelumnya.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

Sebagai praktik terbaik keamanan tentang membatasi pengungkapan informasi, antarmuka pengguna OpenAPI (antarmuka pengguna Swagger, ReDoc, Skalar) hanya boleh diaktifkan di lingkungan pengembangan. Misalnya, lihat Konfigurasi Swagger OAuth 2.0.

Buka aplikasi dan navigasi ke https://localhost:<port>/swagger untuk melihat antarmuka pengguna Swagger.

Untuk meluncurkan aplikasi secara otomatis di URL UI Swagger dengan menggunakan profil httpsProperties/launchSettings.json:

• Konfirmasikan bahwa launchBrowser diaktifkan (true).
• Atur launchUrl ke swagger.

"launchBrowser": true,
"launchUrl": "swagger",

Menggunakan Skalar untuk dokumentasi API interaktif

Skalar adalah UI dokumen interaktif sumber terbuka untuk OpenAPI. Skalar dapat diintegrasikan dengan titik akhir OpenAPI yang disediakan oleh ASP.NET Core. Untuk mengonfigurasi Skalar, instal Scalar.AspNetCore paket.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();

Luncurkan aplikasi dan navigasi ke https://localhost:<port>/scalar untuk melihat antarmuka pengguna Skalar.

Untuk meluncurkan aplikasi secara otomatis di URL antarmuka pengguna Scalar menggunakan profil https dari Properties/launchSettings.json:

• Konfirmasikan bahwa launchBrowser diaktifkan (true).
• Atur launchUrl ke scalar.

"launchBrowser": true,
"launchUrl": "scalar",

Lint menghasilkan dokumen OpenAPI dengan Spectral

Spectral adalah linter dokumen OpenAPI sumber terbuka. Spectral dapat dimasukkan ke dalam build aplikasi untuk memverifikasi kualitas dokumen OpenAPI yang dihasilkan. Instal Spectral sesuai dengan petunjuk penginstalan paket.

Untuk memanfaatkan Spectral untuk menautkan dokumen OpenAPI pada waktu build, pertama-tama Microsoft.Extensions.ApiDescription.Server instal paket untuk mengaktifkan pembuatan dokumen OpenAPI build-time.

Aktifkan pembuatan dokumen pada waktu build dengan mengatur properti berikut dalam file aplikasi .csproj ":

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

Jalankan dotnet build untuk menghasilkan dokumen.

dotnet build

Buat .spectral.yml file dengan konten berikut.

extends: ["spectral:oas"]

Jalankan spectral lint pada file yang dihasilkan.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Dukungan untuk menyuntikkan IOpenApiDocumentProvider

Anda dapat menyuntikkan IOpenApiDocumentProvider ke layanan Anda melalui injeksi dependensi untuk mengakses dokumen OpenAPI secara terprogram, bahkan di luar konteks permintaan HTTP.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

Daftarkan layanan dalam kontainer DI Anda:

builder.Services.AddScoped<DocumentService>();

Ini memungkinkan skenario seperti menghasilkan SDK klien, memvalidasi kontrak API dalam proses latar belakang, atau mengekspor dokumen ke sistem eksternal.

Dukungan untuk menyuntikkan IOpenApiDocumentProvider diperkenalkan di ASP.NET Core di .NET 10. Untuk informasi selengkapnya, lihat dotnet/aspnetcore #61463.