Condividi tramite

Creazione di pagine della Guida per API Web ASP.NET

  • Articolo

Questa esercitazione con il codice illustra come creare pagine della Guida per API Web ASP.NET in ASP.NET 4.x.

Quando si crea un'API Web, spesso è utile creare una pagina della Guida, in modo che altri sviluppatori sappiano come chiamare l'API. È possibile creare manualmente tutta la documentazione, ma è preferibile generare il più possibile. Per semplificare questa attività, API Web ASP.NET fornisce una libreria per la generazione automatica delle pagine della Guida in fase di esecuzione.

Screenshot della pagina della guida A P dot NET A P, che mostra i prodotti A P I disponibili da selezionare e le relative descrizioni.

Creazione di pagine della Guida API

Installare ASP.NET and Web Tools aggiornamento 2012.2. Questo aggiornamento integra le pagine della Guida nel modello di progetto API Web.

Creare quindi un nuovo progetto ASP.NET MVC 4 e selezionare il modello di progetto API Web. Il modello di progetto crea un controller API di esempio denominato ValuesController. Il modello crea anche le pagine della Guida dell'API. Tutti i file di codice per la pagina della Guida vengono inseriti nella cartella Aree del progetto.

Screenshot delle opzioni di menu del modello di progetto Web A P, che circondano l'area e le cartelle della pagina della Guida.

Quando si esegue l'applicazione, la home page contiene un collegamento alla pagina della Guida dell'API. Dalla home page il percorso relativo è /Help.

Screenshot della home page, che punta alle lettere A P selezionabili che apriranno il collegamento alla pagina della Guida.

Questo collegamento consente di visualizzare una pagina di riepilogo API.

Screenshot della pagina della Guida di riepilogo A P, che mostra i diversi valori A P I e la relativa descrizione.

La visualizzazione MVC per questa pagina è definita in Aree/HelpPage/Views/Help/Index.cshtml. È possibile modificare questa pagina per modificare il layout, l'introduzione, il titolo, gli stili e così via.

La parte principale della pagina è una tabella di API raggruppate da controller. Le voci della tabella vengono generate dinamicamente usando l'interfaccia IApiExplorer . Si parlerà più avanti di questa interfaccia. Se si aggiunge un nuovo controller API, la tabella viene aggiornata automaticamente in fase di esecuzione.

La colonna "API" elenca il metodo HTTP e l'URI relativo. La colonna "Description" contiene la documentazione per ogni API. Inizialmente, la documentazione è solo testo segnaposto. Nella sezione successiva verrà illustrato come aggiungere la documentazione dai commenti XML.

Ogni API ha un collegamento a una pagina con informazioni più dettagliate, tra cui i corpi di richiesta e risposta di esempio.

Screenshot di uno dei valori di selezione A P, che mostra le informazioni sulla risposta e i formati del corpo della risposta.

Aggiunta di pagine della Guida a un progetto esistente

È possibile aggiungere pagine della Guida a un progetto API Web esistente usando Gestione pacchetti NuGet. Questa opzione è utile iniziare da un modello di progetto diverso rispetto al modello "API Web".

Dal menu Strumenti selezionare Gestione pacchetti NuGet e quindi console di Gestione pacchetti. Nella finestra Console di Gestione pacchetti digitare uno dei comandi seguenti:

Per un'applicazione C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Per un'applicazione Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Esistono due pacchetti, uno per C# e uno per Visual Basic. Assicurarsi di usare quella corrispondente al progetto.

Questo comando installa gli assembly necessari e aggiunge le visualizzazioni MVC per le pagine della Guida (disponibili nella cartella Aree/HelpPage). È necessario aggiungere manualmente un collegamento alla pagina della Guida. L'URI è /Help. Per creare un collegamento in una visualizzazione razor, aggiungere quanto segue:

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

Assicurarsi inoltre di registrare le aree. Nel file Global.asax aggiungere il codice seguente al metodo Application_Start , se non è già presente:

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

Aggiunta della documentazione dell'API

Per impostazione predefinita, le pagine della Guida hanno stringhe segnaposto per la documentazione. È possibile usare i commenti della documentazione XML per creare la documentazione. Per abilitare questa funzionalità, aprire il file Aree/HelpPage/App_Start/HelpPageConfig.cs e annullare ilcommento della riga seguente:

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Abilitare ora la documentazione XML. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Proprietà. Selezionare la pagina Compila .

Screenshot del menu a discesa del progetto nella finestra esplora soluzioni, evidenziando l'opzione di compilazione.

In Output controllare il file di documentazione XML. Nella casella di modifica digitare "App_Data/XmlDocument.xml".

Screenshot della finestra di dialogo Output, che mostra il percorso di output e l'opzione per selezionare il file di documentazione X M L.

Aprire quindi il codice per il ValuesController controller API, definito in /Controller/ValuesController.cs. Aggiungere alcuni commenti della documentazione ai metodi del controller. Ad esempio:

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

Nota

Suggerimento: se si posiziona il caret sulla riga sopra il metodo e si digitano tre barre in avanti, Visual Studio inserisce automaticamente gli elementi XML. È quindi possibile compilare gli spazi vuoti.

Compilare ed eseguire di nuovo l'applicazione e passare alle pagine della Guida. Le stringhe di documentazione devono essere visualizzate nella tabella API.

Screenshot della tabella A P I nelle pagine della Guida, che mostra la stringa di documentazione nel valore e nella descrizione A P.

La pagina della Guida legge le stringhe dal file XML in fase di esecuzione. Quando si distribuisce l'applicazione, assicurarsi di distribuire il file XML.

Sotto il cappuccio

Le pagine della Guida sono basate sulla classe ApiExplorer , che fa parte del framework API Web. La classe ApiExplorer fornisce il materiale non elaborato per la creazione di una pagina della Guida. Per ogni API , ApiExplorer contiene un'APIDescription che descrive l'API. A questo scopo, un'API viene definita come combinazione di metodo HTTP e URI relativi. Ecco ad esempio alcune API distinte:

  • GET /api/Products
  • GET /api/Products/{id}
  • POST /api/Products

Se un'azione controller supporta più metodi HTTP, ApiExplorer considera ogni metodo come API distinta.

Per nascondere un'API dall'ApiExplorer, aggiungere l'attributo ApiExplorerSettings all'azione e impostare IgnoreApi su true.

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

È anche possibile aggiungere questo attributo al controller per escludere l'intero controller.

La classe ApiExplorer ottiene stringhe di documentazione dall'interfaccia IDocumentationProvider . Come illustrato in precedenza, la libreria Help Pages fornisce un IDocumentationProvider che ottiene la documentazione dalle stringhe di documentazione XML. Il codice si trova in /Areas/HelpPage/XmlDocumentationProvider.cs. È possibile ottenere la documentazione da un'altra origine scrivendo IDocumentationProvider. Per collegarlo, chiamare il metodo di estensione SetDocumentationProvider , definito in HelpPageConfigurationExtensions

ApiExplorer chiama automaticamente l'interfaccia IDocumentationProvider per ottenere stringhe di documentazione per ogni API. Li archivia nella proprietà Documentation degli oggetti ApiDescription e ApiParameterDescription .

Passaggi successivi

Le pagine della Guida visualizzate qui non sono limitate. In effetti, ApiExplorer non è limitato alla creazione di pagine della Guida. Yao Huang Lin ha scritto alcuni grandi post di blog per farti pensare fuori dalla scatola: