Tworzenie stron pomocy dla internetowego interfejsu API ASP.NET

W tym samouczku z kodem pokazano, jak utworzyć strony pomocy dla internetowego interfejsu API ASP.NET w programie ASP.NET 4.x.

Podczas tworzenia internetowego interfejsu API często warto utworzyć stronę pomocy, aby inni deweloperzy wiedzieli, jak wywoływać interfejs API. Całą dokumentację można utworzyć ręcznie, ale lepiej jest automatycznie wygenerować jak najwięcej. Aby ułatwić to zadanie, ASP.NET Web API udostępnia bibliotekę do automatycznego generowania stron pomocy w czasie działania.

Zrzut ekranu przedstawiający stronę pomocy A S P DOT A P I, przedstawiającą dostępne produkty A P I do wyboru i ich opisy.

Tworzenie stron pomocy API

Zainstaluj ASP.NET i Web Tools 2012.2 Update. Ta aktualizacja dodaje strony pomocy do szablonu projektu interfejsu API sieci Web.

Następnie utwórz nowy projekt ASP.NET MVC 4 i wybierz szablon projektu internetowego interfejsu API. Szablon projektu tworzy przykładowy kontroler interfejsu API o nazwie ValuesController. Szablon tworzy również strony pomocy dla interfejsu API. Wszystkie pliki kodu strony pomocy są umieszczane w folderze Obszary projektu.

Zrzut ekranu przedstawiający opcje menu szablonu projektu Web A P I, krążące wokół obszaru i folderów stron pomocy.

Po uruchomieniu aplikacji strona główna zawiera link do strony pomocy interfejsu API. Na stronie głównej ścieżka względna to /Help.

Zrzut ekranu strony głównej, wskazujący na klikalne litery A P I, które otworzą link do strony pomocy.

Ten link umożliwia wyświetlenie strony podsumowania interfejsu API.

Zrzut ekranu strony pomocy podsumowania API, pokazujący różne wartości API oraz ich opisy.

Widok MVC dla tej strony jest zdefiniowany w pliku Areas/HelpPage/Views/Help/Index.cshtml. Możesz edytować tę stronę, aby zmodyfikować układ, wprowadzenie, tytuł, style itd.

Główną częścią strony jest tabela interfejsów API pogrupowana według kontrolera. Wpisy tabeli są generowane dynamicznie przy użyciu interfejsu IApiExplorer . (Porozmawiam więcej o tym interfejsie później). Jeśli dodasz nowy kontroler interfejsu API, tabela zostanie automatycznie zaktualizowana w czasie wykonywania.

Kolumna "API" zawiera listę metod HTTP i względnych URI. Kolumna "Opis" zawiera dokumentację dla każdego interfejsu API. Początkowo dokumentacja jest tylko tekstem zastępczym. W następnej sekcji pokażę, jak dodać dokumentację z komentarzy XML.

Każdy interfejs API ma link do strony z bardziej szczegółowymi informacjami, w tym przykładowe treści żądań i odpowiedzi.

Zrzut ekranu przedstawiający jedną z wartości wyboru A P I z informacjami o odpowiedzi i formatami treści odpowiedzi.

Dodawanie stron pomocy do istniejącego projektu

Można dodawać strony pomocy do istniejącego projektu Web API przy użyciu Menedżera pakietów NuGet. Ta opcja jest przydatna, gdy rozpoczynasz pracę z innym szablonem projektu niż projekt Web API.

W menu Narzędzia wybierz pozycję Menedżer pakietów NuGet, a następnie wybierz pozycję Konsola menedżera pakietów. W oknie Konsola menedżera pakietów wpisz jedno z następujących poleceń:

W przypadku aplikacji w języku C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

W przypadku aplikacji Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Istnieją dwa pakiety: jeden dla języka C# i jeden dla języka Visual Basic. Upewnij się, że używasz tego, który jest zgodny z projektem.

To polecenie instaluje niezbędne zestawy i dodaje widoki MVC dla stron pomocy (znajdujących się w folderze Areas/HelpPage). Musisz ręcznie dodać link do strony Pomoc. Identyfikator URI to /Help. Aby utworzyć link w widoku razor, dodaj następujące elementy:

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

Pamiętaj również, aby zarejestrować obszary. W pliku Global.asax dodaj następujący kod do metody Application_Start , jeśli jeszcze nie istnieje:

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

    // ...
}

Dodawanie dokumentacji interfejsu API

Domyślnie strony pomocy mają ciągi zastępcze dla dokumentacji. Aby utworzyć dokumentację, możesz użyć komentarzy dokumentacji XML . Aby włączyć tę funkcję, otwórz plik Areas/HelpPage/App_Start/HelpPageConfig.cs i usuń komentarz w następującym wierszu:

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

Teraz włącz dokumentację XML. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy projekt i wybierz polecenie Właściwości. Wybierz stronę Build.

Zrzut ekranu przedstawiający menu rozwijane projektu w oknie eksploratora rozwiązań z wyróżnioną opcją kompilacji.

W obszarze Dane wyjściowe sprawdź plik dokumentacji XML. W polu edycji wpisz "App_Data/XmlDocument.xml".

Zrzut ekranu przedstawiający okno dialogowe Wyjście, pokazujące ścieżkę wyjściową i opcję wyboru pliku dokumentacji X M L.

Następnie otwórz kod kontrolera interfejsu ValuesController API, który jest zdefiniowany w /Controllers/ValuesController.cs. Dodaj komentarze dokumentacyjne do metod kontrolera. Przykład:

/// <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";
}

Uwaga / Notatka

Wskazówka: Jeśli umieścisz kursor w wierszu powyżej metody i wpiszesz trzy ukośniki przednie, program Visual Studio automatycznie wstawia elementy XML. Następnie możesz wypełnić puste.

Teraz skompiluj i uruchom ponownie aplikację i przejdź do stron pomocy. Ciągi dokumentacji powinny być wyświetlane w tabeli interfejsu API.

Zrzut ekranu przedstawiający tabelę A P I na stronach pomocy, pokazujący ciąg dokumentacji zawarty w wartości i opisie A P I.

Strona pomocy odczytuje ciągi z pliku XML w czasie wykonywania. (Podczas wdrażania aplikacji upewnij się, że wdrożono plik XML).

Pod kapturem

Strony pomocy są oparte na klasie ApiExplorer , która jest częścią struktury internetowego interfejsu API. Klasa ApiExplorer udostępnia materiał pierwotny do tworzenia strony pomocy. Dla każdego API, ApiExplorer zawiera ApiDescription, które opisuje API. W tym celu "interfejs API" jest definiowany jako kombinacja metody HTTP i względnego identyfikatora URI. Oto na przykład kilka odrębnych interfejsów API:

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

Jeśli akcja kontrolera obsługuje wiele metod HTTP, interfejs APIExplorer traktuje każdą metodę jako odrębny interfejs API.

Aby ukryć interfejs API przed ApiExplorer, dodaj atrybut ApiExplorerSettings do akcji i ustaw IgnoreApi na wartość true.

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

Możesz również dodać ten atrybut do kontrolera, aby wykluczyć cały kontroler.

Klasa ApiExplorer pobiera ciągi dokumentacji z interfejsu IDocumentationProvider . Jak pokazano wcześniej, biblioteka Stron pomocy udostępnia element IDocumentationProvider , który pobiera dokumentację z ciągów dokumentacji XML. Kod znajduje się w folderze /Areas/HelpPage/XmlDocumentationProvider.cs. Dokumentację możesz uzyskać z innego źródła, pisząc własny element IDocumentationProvider. Aby go skonfigurować, wywołaj metodę rozszerzenia SetDocumentationProvider, zdefiniowaną w HelpPageConfigurationExtensions

APIExplorer automatycznie wywołuje interfejs IDocumentationProvider w celu uzyskania ciągów dokumentacji dla każdego API. Przechowuje je we właściwości Documentation obiektów ApiDescription i ApiParameterDescription .

Dalsze kroki

Nie ograniczasz się do stron pomocy przedstawionych tutaj. W rzeczywistości usługa ApiExplorer nie jest ograniczona do tworzenia stron pomocy. Yao Huang Lin napisał kilka świetnych wpisów na blogu, które pomogą ci myśleć nieszablonowo.

  • Last updated on