dokumentasi API web ASP.NET Core dengan Swagger/OpenAPI

Oleh Christoph Nienaber dan Rico Suter

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 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, dikurangi untuk brevity:

{
  "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. Baik Swashbuckle maupun NSwag menyertakan versi UI Swagger yang disematkan, sehingga dapat dihosting di aplikasi ASP.NET Core Anda menggunakan panggilan pendaftaran 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 Contoh petstore.

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

Curl berikut meneruskan token JWT untuk menguji titik akhir antarmuka pengguna Swagger:

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

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

Buat file dokumentasi XML pada waktu kompilasi.

Lihat GenerateDocumentationFile untuk informasi selengkapnya.

Langkah berikutnya

• Mulai menggunakan Swashbuckle
• Mulai menggunakan NSwag