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 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 internetowy interfejs API udostępnia bibliotekę do automatycznego generowania stron pomocy w czasie wykonywania.

Tworzenie stron pomocy interfejsu API

Zainstaluj aktualizację ASP.NET and Web Tools 2012.2. Ta aktualizacja integruje strony pomocy z szablonem projektu internetowego interfejsu API.

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 interfejsu API. Wszystkie pliki kodu strony pomocy są umieszczane w folderze Obszary projektu.

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

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

Widok MVC dla tej strony jest zdefiniowany w obszarze Obszary/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ę metody HTTP i względnego identyfikatora URI. Kolumna "Opis" zawiera dokumentację każdego interfejsu API. Początkowo dokumentacja jest po prostu 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ładowymi treściami żądań i odpowiedzi.

Dodawanie stron pomocy do istniejącego projektu

Strony pomocy można dodać do istniejącego projektu internetowego interfejsu API przy użyciu Menedżera pakietów NuGet. Ta opcja jest przydatna, rozpoczynając od innego szablonu projektu niż szablon "Internetowy interfejs 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 pasuje do projektu.

To polecenie instaluje niezbędne zestawy i dodaje widoki MVC dla stron pomocy (znajdujących się w folderze Obszary/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 Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt i wybierz polecenie Właściwości. Wybierz stronę Kompilacja .

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

Następnie otwórz kod kontrolera interfejsu ValuesController API, który jest zdefiniowany w pliku /Controllers/ValuesController.cs. Dodaj komentarze dokumentacji do metod kontrolera. Na 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

Porada: Jeśli umieścisz daszek w wierszu nad metodą i wpisz trzy ukośniki do przodu, program Visual Studio automatycznie wstawia elementy XML. Następnie możesz wypełnić puste pusty.

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

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 surowiec do tworzenia strony pomocy. Dla każdego interfejsu API interfejs APIExplorer zawiera opis interfejsu 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, usługa ApiExplorer traktuje każdą metodę jako odrębny interfejs API.

Aby ukryć interfejs API z interfejsu APIExplorer, dodaj atrybut ApiExplorerSettings do akcji i ustaw wartość IgnoreApi na 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 pliku /Areas/HelpPage/XmlDocumentationProvider.cs. Dokumentację możesz uzyskać z innego źródła, pisząc własny obiekt IDocumentationProvider. Aby go połączyć, wywołaj metodę rozszerzenia SetDocumentationProvider zdefiniowaną w pliku HelpPageConfigurationExtensions

Interfejs APIExplorer automatycznie wywołuje interfejs IDocumentationProvider , aby uzyskać ciągi dokumentacji dla każdego interfejsu API. Przechowuje je we właściwości Documentation obiektów ApiDescription i ApiParameterDescription .

Następne 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 w blogu, aby wymyślić z pudełka:

• Dodawanie prostego klienta testowego do strony pomocy interfejsu API sieci Web ASP.NET
• Tworzenie strony pomocy internetowego interfejsu API ASP.NET na temat usług hostowanych samodzielnie
• Generowanie strony pomocy (lub klienta) w czasie projektowania dla internetowego interfejsu API ASP.NET
• Zaawansowane dostosowania strony pomocy