Condividi tramite

Creazione di pagine della Guida per ASP.NET API Web

Questa esercitazione mostra con codice come creare pagine di aiuto per l'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 automaticamente il più possibile. Per semplificare questa attività, ASP.NET Web API fornisce una libreria per la generazione automatica delle pagine della Guida a runtime.

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

Creazione di pagine di aiuto dell'API

Installare ASP.NET e Web Tools 2012.2 Update. 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 I, che circondano l'area e le cartelle delle pagine 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 selezionabili API che apriranno il collegamento alla pagina di aiuto.

Questo collegamento consente di visualizzare una pagina di riepilogo dell'API.

screenshot della pagina di riepilogo API, che mostra i diversi valori API 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 per controller. Le voci della tabella vengono generate in modo dinamico, usando l'interfaccia IApiExplorer . Più avanti parlerò 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, inclusi i corpi di richiesta e risposta di esempio.

Screenshot di uno dei valori di selezione A P I, 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 per 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

Sono disponibili due pacchetti, uno per C# e uno per Visual Basic. Assicurarsi di usare quello corrispondente al progetto.

Questo comando installa gli assembly necessari e aggiunge le visualizzazioni MVC per le pagine della Guida ,che si trovano nella cartella Areas/HelpPage. È necessario aggiungere manualmente un collegamento alla pagina della Guida. L'URI è /Help. Per creare un collegamento in una vista 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 di aiuto 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 rimuovere il commento dalla 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 Outputselezionare 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 /Controllers/ValuesController.cs. Aggiungere alcuni commenti di documentazione ai metodi del controller. Per 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";
}

Annotazioni

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

Ora costruisci ed esegui nuovamente l'applicazione e naviga alle pagine di aiuto. Le stringhe della documentazione devono essere visualizzate nella tabella API.

Screenshot della tabella A P I nei documenti di aiuto, che mostra la stringa di documentazione nel valore e nella descrizione dell'A P I.

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

Sotto il cofano

Le pagine della guida sono basate sulla classe ApiExplorer, che fa parte del framework di API Web. La classe ApiExplorer fornisce la materia prima per la creazione di una pagina di aiuto. Per ogni API , ApiExplorer contiene un ApiDescription che descrive l'API. A questo scopo, un 'API' viene definito come combinazione di metodo HTTP e URI relativo. Ecco ad esempio alcune API distinte:

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

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

Per nascondere un'API da 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 le stringhe di documentazione dall'interfaccia IDocumentationProvider . Come illustrato in precedenza, la libreria delle pagine di aiuto fornisce un'interfaccia 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 nell'interfaccia IDocumentationProvider per ottenere stringhe di documentazione per ogni API. Li archivia nella proprietà Documentation degli oggetti ApiDescription e ApiParameterDescription .

Passaggi successivi

Non sei limitato alle pagine della Guida mostrate qui. Infatti, ApiExplorer non si limita alla creazione di pagine guida. Yao Huang Lin ha scritto alcuni ottimi post di blog per farti pensare fuori dalla scatola:

  • Last updated on