Interaktywna dokumentacja API – Swagger

Jedną z pierwszych rzeczy jaką robię, gdy tworzę nowe API, jest dodanie narzędzia Swagger. Umożliwia ono w szybki i prosty sposób przetestować API. Używam go również, gdy chcę łatwo wywołać jakiś endpoint.

Swagger

Jest to narzędzie, które udostępnia interaktywną dokumentację API. Taka dokumentacja domyślnie jest udostępniona pod adresem:

http[s]://<base_url>/swagger

A wygląda następująco:

Na tej stronie mamy spis wszystkich naszych punktów wejścia (endpoints) wraz z akcjami umożliwiającymi wysłanie żądania (request) do naszej aplikacji.

Konfiguracja

Aby dodać narzędzie Swagger do naszej aplikacji, należy dołączyć paczkę:

Swashbuckle.AspNetCore

ConfigureServices

A następnie w pliku, gdzie konfigurujemy naszą aplikację (Startup.cs), musimy dodać generowanie dokumentacji dla narzędzia Swagger:

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API" });
    });
    // ...
}

Metoda AddSwaggerGen jako parametr przyjmuje akcję ustawiającą opcje generacji narzędzia Swagger (obiekt typu SwaggerGenOptions). W tej akcji, na obiekcie opcji generacji, wołamy metodę SwaggerDoc. Pierwszym parametrem tej metody jest nazwa, a drugim obiekt Info w którym ustawiamy tytuł widoczny na stronie interaktywnej dokumentacji.

Configure

Teraz musimy jeszcze ustawić, aby nasza aplikacja używała wygenerowanej dokumentacji dla narzędzia Swagger:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // ...
    app.UseSwagger();
    app.UseSwaggerUI(c => 
    { 
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); 
    });
    // ...
}

Na początku wywołujemy metodę UseSwagger, która udostępnia możliwość użycia narzędzia Swagger. Następnie wywołujemy metodę UseSwaggerUI, która tworzy interaktywną dokumentację. Ta metoda jako parametr przyjmuje akcję ustawiającą opcje interaktywnej dokumentacji (obiekt typu SwaggerUIOptions). W tej akcji, na obiekcie opcji, wywołujemy metodę SwaggerEndpoint. Przyjmuje ona dwa parametry. Pierwszym jest adres url do wygenerowanej dokumentacji. Dokumentacja generuje się pod adresem:

/swagger/<nazwa z metody SwaggerDoc>/swagger.json

Drugim parametrem jest nazwa widoczna w prawym górnym rogu naszej interaktywnej dokumentacji w kontrolce drop-down (przy „Select a space”).

I to tyle. Dodanie 1 paczki oraz 3 linijek kodu powoduje, że mamy dostępną interaktywną dokumentację naszego API.

Dodatkowe informacje

Tylko na środowisku developerskim

Bardzo często narzędzie Swagger dodajemy tylko dla programistów (oraz ewentualnie testerów) i nie chcemy, aby było dostępne na produkcji. W takiej sytuacji w metodzie Configure warto dodać użycie narzędzia Swagger tylko, gdy mamy środowisko developerskie (i/lub testerskie). Można to zrobić na przykład tak:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // ...
    if (env.IsDevelopment())
    {
        app.UseSwagger();
        app.UseSwaggerUI(c => 
        { 
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); 
        });
    }
    // ...
}

W przedstawionym przykładzie narzędzie Swagger zostanie dodane tylko wtedy, kiedy zmienna środowiskowa „ASPNETCORE_ENVIRONMENT” będzie ustawiona na „Development” (jest to domyślne ustawienie gdy uruchamiamy aplikację lokalnie).

Strona startowa

Czasami wygodne jest ustawienie, aby domyślnie pierwszą stroną, gdy uruchamiamy aplikację lokalnie, była nasza interaktywna dokumentacja API. Można to zrobić edytując profil uruchomienia aplikacji (z reguły jest to profil IIS Express). Aby to zrobić wchodzimy we właściwości projektu i wybieramy sekcję „Debug”. Następnie w elemencie Lunch browser ustawiamy adres do narzędzia Swagger (domyślnie jest to: „swagger”).

Inny adres

Jeśli z jakiegoś powodu nie podoba nam się adres „swagger” i chcielibyśmy go zmienić, to w metodzie UseSwaggerUI należy ustawić RoutePrefix na docelową wartość (np. „docs”):

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // ...
    if (env.IsDevelopment())
    {
        app.UseSwagger();
        app.UseSwaggerUI(c => 
        { 
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            c.RoutePrefix = "docs"; 
        });
    }
    // ...
}