dokumentasi API web ASP.NET Core dengan Swagger/OpenAPI

Oleh Rico Suter

Artikel ini membahas penggunaan alat Swagger — disediakan oleh paket Swashbuckle.AspNetCore dan NSwag — untuk menghasilkan dokumentasi OpenAPI dan halaman bantuan interaktif untuk API web ASP.NET Core.

Di .NET 9 dan yang lebih baru, ASP.NET Core menyertakan dukungan OpenAPI bawaan yang menggantikan Swashbuckle sebagai default. Swashbuckle tidak lagi disertakan dalam templat proyek, tetapi tetap tersedia sebagai paket komunitas yang dapat Anda tambahkan secara manual.

• Untuk memahami fitur OpenAPI bawaan, lihat Ringkasan dukungan OpenAPI di ASP.NET aplikasi Core API.
• Untuk menambahkan antarmuka pengguna Swagger untuk eksplorasi interaktif atau pengujian ad-hoc lokal bersama dukungan OpenAPI bawaan, lihat Menggunakan dokumen OpenAPI yang dihasilkan.

Instruksi berikut berlaku untuk proyek menggunakan Swashbuckle atau NSwag dengan ASP.NET Core 8.0 dan yang lebih lama.

Swagger (OpenAPI) adalah spesifikasi agnostik bahasa untuk menjelaskan REST API. Ini memungkinkan komputer dan manusia untuk memahami kemampuan REST API tanpa akses langsung ke kode sumber. Tujuan utamanya adalah untuk:

• Minimalkan jumlah pekerjaan yang diperlukan untuk menyambungkan layanan yang dipisahkan.
• Kurangi jumlah waktu yang diperlukan untuk mendokumentasikan layanan secara akurat.

Dua implementasi OpenAPI utama untuk .NET adalah Swashbuckle dan NSwag, lihat:

• Memulai dengan Swashbuckle
• Memulai dengan NSwag

OpenAPI vs. Swagger

Proyek Swagger di sumbangkan ke OpenAPI Initiative pada tahun 2015 dan sejak itu disebut sebagai OpenAPI. Kedua nama digunakan secara bergantian. Namun, "OpenAPI" mengacu pada spesifikasinya. "Swagger" mengacu pada keluarga produk sumber terbuka dan komersial dari SmartBear yang bekerja dengan Spesifikasi OpenAPI. Produk sumber terbuka berikutnya, seperti OpenAPIGenerator, juga termasuk dalam nama keluarga Swagger, meskipun tidak dirilis oleh SmartBear.

Singkatnya:

• OpenAPI adalah spesifikasi.
• Swagger adalah alat yang menggunakan spesifikasi OpenAPI. Misalnya, OpenAPIGenerator dan SwaggerUI.

Spesifikasi OpenAPI (openapi.json)

Spesifikasi OpenAPI adalah dokumen yang menjelaskan kemampuan API Anda. Dokumen didasarkan pada XML dan anotasi atribut dalam pengontrol dan model. Ini adalah bagian inti dari alur OpenAPI dan digunakan untuk mendorong alat seperti SwaggerUI. Secara default, ini bernama openapi.json. Berikut adalah contoh spesifikasi OpenAPI yang telah dipersingkat untuk kejelasan:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Antarmuka Pengguna Swagger

UI Swagger menawarkan UI berbasis web yang menyediakan informasi tentang layanan, menggunakan spesifikasi OpenAPI yang dihasilkan. Swashbuckle dan NSwag keduanya menyertakan versi Swagger UI tertanam, sehingga dapat dihosting di aplikasi ASP.NET Core Anda menggunakan panggilan registrasi middleware. Antarmuka pengguna web terlihat seperti ini:

Setiap metode tindakan publik di pengontrol Anda dapat diuji dari UI. Pilih nama metode untuk memperluas bagian. Tambahkan parameter yang diperlukan, dan pilih Cobalah!.

Catatan

Versi UI Swagger yang digunakan untuk cuplikan layar adalah versi 2. Untuk contoh versi 3, lihat Petstore Example.

Mengamankan titik akhir UI Swagger

Panggil MapSwagger().RequireAuthorization untuk mengamankan titik akhir antarmuka pengguna Swagger. Contoh berikut mengamankan titik akhir swagger:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

  if (app.Environment.IsDevelopment())
  {
    app.UseSwagger();
    app.UseSwaggerUI();
  }

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Dalam kode sebelumnya, /weatherforecast titik akhir tidak memerlukan otorisasi, tetapi titik akhir Swagger memang memerlukannya.

Curl berikut meneruskan token JWT untuk menguji endpoint Swagger UI.

curl -i -H "Authorization: Bearer {TOKEN}" https://localhost:{PORT}/swagger/v1/swagger.json

di mana {TOKEN} penampung adalah token pembawa JWT dan {PORT} penampung adalah nomor port.

Untuk informasi selengkapnya tentang pengujian dengan token JWT, lihat Membuat token dengan dotnet user-jwts.

Membuat file dokumentasi XML pada waktu kompilasi

Lihat GenerateDocumentationFile untuk informasi selengkapnya.

Langkah berikutnya

• Mulai menggunakan Swashbuckle
• Mulai menggunakan NSwag