Di recente ho lavorato al backend di un’applicazione per un nostro cliente. Alcuni tasks erano relativi all’introduzione di nuove API da annotare con Swagger ed, in particolare, uno di questi richiedeva di abilitare Swagger solo per l’environment di debug e disabilitarlo per quello di produzione.

Ma cos’è Swagger? Si tratta di un set di tool che fanno da contorno alla specifica OpenApi (OAS), ovvero lo standard per la descrizione delle API Rest, per creare e documentare tali API. Lo standard OAS è indipendente dal linguaggio di programmazione ed è stato pensato per essere compreso sia dalle persone che dai computer. Lo scopo è rendere più comprensibile ciò che viene messo a disposizione da un servizio, senza dover accedere al codice sorgente o ad ulteriore documentazione.

In un progetto .Net è possibile integrare Swagger installando, tramite Nuget, il pacchetto Open Source Swashbuckle. Una volta installato, troveremo nella cartella App_start il file SwaggerConfig.cs.

Tale file contiene diversi commenti utili alla configurazione di Swagger per la nostra applicazione. In particolare possiamo indicare un file XML dove verranno salvati i commenti con cui possiamo annotare le nostre API.

c.IncludeXmlComments(GetXmlCommentsPath());

Per evitare errori bisogna a questo punto andare nelle proprietà del progetto e nella scheda Build, sezione Output, flaggare l’opzione “XML documentation file”, indicando il file XML di destinazione.

Terminata questa configurazione è possibile annotare le API con i seguenti tags :

• Summary

/// <summary>
/// Esempio Commenti Swagger
/// </summary>

• Remarks

/// <remarks>Osservazioni </remarks>

• Parameter

/// <param name="id" cref="int">Value id</param>
/// <param name="value" cref="string">Value string</param>

• Response

///<response code="500">Ops!!! Error 500 </response>

Consideriamo la seguente action che effettua una GET.

/// <summary>
/// Esempio Commenti Swagger
/// </summary>
/// <param name="id" cref="int">Value id</param>
/// <param name="value" cref="string">Value string</param>
/// <remarks>Osservazioni </remarks>
///<response code="500">Ops!!! Error 500 </response>
public string Get(int id, string value)
{
    return value+id.ToString();
}

Possiamo vedere il risultato delle annotazioni nella SwaggerUI raggiungibile all’indirizzo: [host]:[port]/swagger.

Come possiamo configurare Swagger rendendolo disponibile solo per l’environment di sviluppo e disabilitarlo invece per quello di produzione? Ci sono dei semplici passaggi per farlo. Innanzitutto definiamo, nel file web.config, una nuova key all’interno del tag <appsettings>:

<appSettings>
    <add key="DisableSwagger" value="False" />
</appSettings>

Successivamente, all’interno del file SwaggerConfig.cs ed in particolare all’interno del metodo Register(), aggiungiamo una controllo sul valore della key definita precendentemente.

if (ConfigurationManager.AppSettings["DisableSwagger"] == "True")
{
    return;
}

Creiamo, quindi, una regola di trasformazione all’interno del Web.Release.config per la quale verrà settato il parametro DisableSwagger al valore true in modo che la condizione non sia verificata per l’environment di produzione.

<add key="DisableSwagger" value="True" xdt:Transform="Replace" xdt:Locator="Match(key)" />

Possiamo vedere l’effetto di questa trasformazione cliccando col tasto destro su Web.Release.config e selezionando “Preview Transform”

Otterremo così l’effetto desiderato:

Semplice e veloce! Spero vi sia utile come lo è stato per me.

Alla prossima