Wykorzystanie SmartSmart do dokumentowania interfejsów API

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

SmartDokumentacja umożliwia dokumentowanie interfejsów API w portalu dla programistów Drupal 7 w taki sposób, że dokumentacja interfejsów API jest w pełni interaktywna. Interaktywna dokumentacja oznacza, że użytkownicy portalu mogą:

• Poczytaj o swoich interfejsach API
• Wysyłaj żądanie na żywo do interfejsu API
• Wyświetlanie odpowiedzi na żywo zwróconej przez interfejs API

Tworząc interaktywną dokumentację interfejsów API, ułatwiasz użytkownikom portalu poznawanie, testowanie i ocenianie interfejsów API.

Interfejs Edge Management API to interfejs API typu REST, który umożliwia dostęp do usług API za pomocą dowolnego klienta HTTP. Apigee korzysta z dokumentów SmartDokumentacja, aby tworzyć interaktywną dokumentację interfejsu Edge Management API. Dokumentację interfejsu API znajdziesz tutaj.

Przykład portalu SmartDokumentacja

Aby korzystać z dokumentu SmartDokumentacja, musisz mieć portal usług dla programistów Apigee. Więcej informacji znajdziesz w artykule o tworzeniu portalu dla programistów.

Na stronie głównej portalu dla programistów kliknij Interfejsy API na górnym pasku nawigacyjnym, aby wyświetlić stronę z dokumentacją interfejsów API.

Portal zawiera 2 interfejsy API: Hello World i Pet Store Example.

Interfejs Hello World API został utworzony na podstawie przykładowej specyfikacji OpenAPI mocktarget.yaml. Więcej informacji znajdziesz na stronie https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

Interfejs Pet Store Example API został utworzony na podstawie klasycznej wersji demonstracyjnej sklepu zoologicznego.

Poznaj interfejs Hello World API:

1. Kliknij Hello World API. Zostanie wyświetlona strona podsumowania interfejsu Hello World API:
   
2. Kliknij Wyświetl potwierdzenie interfejsu API. Dokumenty inteligentne dla tego zasobu są wyświetlane:
   
3. Kliknij Wyślij tę prośbę.
4. Wyświetl zwróconą odpowiedź:

   HTTP/1.1 200 OK
   Connection:
   keep-alive
   Content-Length:
   18
   Content-Type:
   text/html; charset=utf-8
   Date:
   Tue, 21 Jun 2016 21:49:32 GMT
   ETag:
   W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
   X-Powered-By:
   Apigee
   <H2>I <3 APIs</H2>
   

5. Kliknij kartę Żądanie, aby wyświetlić żądanie, lub cURL, aby wyświetlić odpowiednie wywołanie cURL.

Jak dokumentować interfejsy API za pomocą SmartDokumentacja

SmartDokumenty reprezentują interfejsy API za pomocą model, w którym model zawiera wszystkie informacje o Twoich interfejsach API. Portal wyodrębnia informacje o interfejsach API z modelu, aby renderować strony dokumentacji w portalu jako węzły Drupal, gdzie każdy węzeł Drupal odpowiada stronie dokumentacji w portalu.

Ogólne czynności, które musisz wykonać, aby korzystać z SmartDokumentów, to:

1. Skonfiguruj moduł Drupal SmartDokumenty w portalu.
2. Utwórz model SmartDokumentów.
3. Dodaj interfejsy API do modelu za pomocą pliku WADL, specyfikacji OpenAPI (dawniej Swagger) lub ręcznie.
4. Renderuj model jako zbiór węzłów Drupal. Każdy węzeł Drupal zawiera informacje o jednym interfejsie API. Jeśli na przykład zasób w Twoim interfejsie API obsługuje zarówno żądanie POST, jak i PUT, SmartDokumentacja utworzy osobny węzeł Drupal dla żądań POST i PUT.
5. Opublikuj węzły Drupal. Po opublikowaniu użytkownicy portalu będą mogli wyświetlać Twój interfejs API i korzystać z niego.
6. Edytuj węzły Drupal przed ich opublikowaniem lub po nim. Węzły Drupal możesz edytować za pomocą edytora Drupal albo oryginalnego pliku WADL lub specyfikacji OpenAPI. Gdy skończysz edytowanie pliku WADL lub specyfikacji OpenAPI, zaimportuj go z powrotem do modelu jako nową wersję, a następnie wyrenderuj i opublikuj zmiany.
7. Włącz TLS. Ponieważ SmartDokumenty mogą wysyłać dane uwierzytelniające do backendu w ramach wysyłania żądań do interfejsów API, musisz włączyć TLS w portalu, by zapewnić bezpieczeństwo tych danych. W środowiskach produkcyjnych i testowych portalu Apigee dostarcza certyfikat TLS wymagany do wysyłania żądań https://. Zanim jednak uruchomisz portal, musisz uzyskać własny certyfikat TLS i włączyć TLS. Więcej informacji znajdziesz w artykule o używaniu TLS w portalu.

Informacje o modelach i szablonach SmartDoc

Gdy utworzysz model w portalu, jest on przechowywany w organizacji Edge, a nie w Drupal. Model to duży blok kodu JSON z nazwą wewnętrzną (np. „my-smartdocs-api”) i definiujący strukturę interfejsu API. Portal renderuje model w języku HTML i zapewnia interfejs do jego edycji. Wszystkie aktualizacje interfejsu API w portalu są automatycznie odsyłane z powrotem do modelu źródłowego.

Załóżmy, że w organizacji masz wiele portali (na przykład dev, Stage i Production). W Panteonie możesz przenosić portal z jednego środowiska do innego. Wygląda na to, że każda instancja portalu zawiera własny model, ale wszystkie odwołują się do modelu źródłowego. Jeśli zmodyfikujesz interfejs API w wersji deweloperskiej, model zostanie zaktualizowany, a zmiany pojawią się w wersji produkcyjnej. Podobnie jeśli usuniesz model w wersji deweloperskiej, źródło zostanie usunięte i nie będzie już dostępne w środowisku produkcyjnym.

Szablony kontrolują wygląd i styl Twoich dokumentów SmartDokumentacja, a szablony te (zarządzane przez uchwyty kierownicy i pliki CSS) są przechowywane w każdej instancji portalu. Dzięki temu każdy portal może teoretycznie używać unikalnego szablonu dla każdego modelu. Jedną z udogodnień platformy renderowania jest automatyczne stosowanie szablonu domyślnego (domyślnego szablonu Apigee lub udostępnionego przez Ciebie szablonu) do każdego modelu.

Poniższy diagram przedstawia relację między modelami a portalami. Zielone strzałki oznaczają automatyczną synchronizację.

To polecenie cURL zawiera listę wszystkich modeli w organizacji:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Konfigurowanie modułu SmartDokumentacja

Apigee wdrożyła SmartDokumenty jako niestandardowy moduł Drupal. Aby skonfigurować moduł SmartDokumenty, wykonaj czynności opisane poniżej.

Aby skonfigurować moduł SmartDokumenty:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administracyjnym Drupal wybierz Modules (Moduły). Pojawi się lista wszystkich zainstalowanych modułów Drupal.
3. Włącz moduł SmartDocs.
4. Zapisz konfigurację.
5. Wybierz Modules (Moduły) w menu administratora Drupal.
6. Wybierz Inteligentne dokumenty -> Uprawnienia i upewnij się, że opcja „Wykonywanie zadań administracyjnych w module SmartDokumenty” jest włączona dla roli „Administrator”.
7. W menu administrowania Drupal wybierz Configuration > Dev Portal (Konfiguracja > Portal dla programistów).
8. Ustaw Limit czasu połączenia i Limit czasu żądania na 16 sekund.
9. Zapisz konfigurację.
10. Skonfiguruj ustawienia adresu URL:
    1. W menu Drupal wybierz Konfiguracja > Wyszukiwanie i metadane > Aliasy URL > Ustawienia.
    2. Ustaw Maksymalną długość aliasu i Maksymalna długość komponentu na 255.
    3. Rozwiń opcję Interpunkcja.
    4. W ustawieniach lewy nawias klamrowy ({) i prawy nawias klamrowy (}) wybierz Brak działania (nie zastępuj).
    5. Kliknij Save setup (Zapisz konfigurację).
11. Jeśli Twój portal dla programistów będzie dostępny dla użytkowników w sieci wewnętrznej bez dostępu do internetu lub jeśli podzbiór interfejsów API znajduje się w sieci prywatnej, skonfiguruj adres URL serwera proxy interfejsu SmartDokumentacja w ten sposób:
    1. W menu Administracja w usłudze Drupal wybierz Konfiguracja > SmartDokumenty.
    2. Rozwiń Ustawienia zaawansowane.
    3. Zaktualizuj pole URL serwera proxy SmartDokumentacja w ten sposób: <host>/smartdocs/v1/sendrequest.
       Wbudowana pomoc powinna zawierać wartość wymaganą dla Twojego środowiska. Na przykład:
       https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest
       
       To pole przyjmuje domyślnie wartość https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Kliknij Save setup (Zapisz konfigurację).

Tworzenie modelu

Model zawiera wszystkie informacje o reprezentacji interfejsu API. Możesz zdefiniować w portalu wiele modeli obsługujących różne interfejsy API lub zgrupować wszystkie interfejsy API w jeden model.

Każdy model określa unikalną nazwę wewnętrzną, która określa też podstawowy adres URL wygenerowanych węzłów Drupala. Adres URL każdego węzła Drupal ma postać:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

gdzie:

• drupalBasePath: podstawowy adres URL portalu.
• internalName: wewnętrzna nazwa modelu.
• httpMethod: metoda HTTP interfejsu API, np. get, put, post lub delete.
• resourcePath: ścieżka zasobu.

Jeśli na przykład określisz nazwę wewnętrzną jako „mójmodel”, URL wygenerowanego węzła Drupal dla żądania GET do zasobu o nazwie „/books” będzie wyglądać tak:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Aby utworzyć model

Gdy utworzysz model, jest on przechowywany w organizacji Edge jako źródło struktury interfejsu API. Więcej informacji znajdziesz w artykule Informacje o modelach i szablonach SmartDoc.

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumenty w menu administrowania Drupal.
3. U góry strony wybierz Nowy model.
4. Wypełnij te pola:
   • Nazwa: nazwa modelu, która będzie wyświetlana w witrynie.
   • Nazwa wewnętrzna: podczas wpisywania Nazwa będzie wyświetlana nazwa wewnętrzna. Wewnętrzna nazwa modelu, która musi być niepowtarzalna wśród wszystkich modeli. Nazwa wewnętrzna może zawierać tylko małe litery, cyfry i łączniki bez spacji. Aby edytować tę nazwę, kliknij Edytuj.
   • Opis: opis modelu.
5. Wybierz Utwórz model.

Gdy utworzysz model, przekierujemy Cię na jego stronę. Następnie za pomocą menu Operacje możesz wybrać:

• Zaimportuj plik WADL z opisem interfejsu API lub podaj adres URL specyfikacji OpenAPI opisującej Twój interfejs API.
• Dodaj wersję do modelu.
• Zmień ustawienia modelu, w tym używane przez niego arkusze stylów.
• Wyeksportuj model do pliku.
• Usuń model.

Dodawanie interfejsów API do modelu

Interfejsy API możesz dodać do modelu przez:

• Importowanie pliku WADL zawierającego definicję interfejsu API
• Importowanie specyfikacji OpenAPI (OpenAPI 2.0 lub 1.2)
• Ręczne tworzenie zasobów i metod

Możesz też zaimportować plik JSON SmartDokumentacja do modelu. Ten plik zwykle tworzy się przez wyeksportowanie istniejącego modelu, edycję pliku, a następnie zaimportowanie aktualizacji. Więcej informacji znajdziesz w sekcji „Eksportowanie i importowanie modelu” poniżej.

Importowanie języka WADL

Po utworzeniu modelu zaimportuj plik WADL z opisem interfejsu API. Za każdym razem, gdy importujesz plik WADL, automatycznie tworzysz nową wersję modelu.

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administrowania Drupal wybierz Treść > SmartDokumentacja.
3. Wybierz model, który chcesz zaktualizować.
4. W sekcji Operacje wybierz Import.
5. Wybierz WADL w menu Wybierz format na stronie importowania Dokumentów Smart Docs.
6. W menu Typ przesyłania wybierz Plik lub URL.
   1. Jeśli wybierzesz Plik, przejdź do pliku WADL.
   2. Jeśli wybierzesz URL, podaj adres URL pliku WADL.
7. Kliknij Importuj, aby zaimportować go do modelu. Możesz teraz renderować model.
8. Nastąpi przekierowanie na stronę z informacjami o modelu, na której możesz go wyrenderować.

Importowanie specyfikacji OpenAPI

Po utworzeniu modelu możesz zaimportować specyfikację OpenAPI (wcześniej Swagger). Edge obsługuje OpenAPI w wersjach 1.2 i 2.0.

OpenAPI korzysta z plików zawierających obiekty JSON do opisywania interfejsu API. Za każdym razem, gdy importujesz specyfikację OpenAPI, automatycznie tworzysz nową wersję modelu.

Aby zaimportować specyfikację OpenAPI:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administrowania Drupal wybierz Treść > SmartDokumentacja.
3. Wybierz model, który chcesz zaktualizować.
4. W sekcji Operacje wybierz Import.
5. Wybierz Swagger JSON lub Swagger YAML w menu Wybierz format na stronie importowania dokumentów SmartDokumentacja.
6. Wybierz Plik lub URL w menu Typ przesyłania (musisz wybrać URL w przypadku OpenAPI 1.2).
   1. Jeśli wybierzesz Plik, przejdź do specyfikacji OpenAPI.
   2. Jeśli wybierzesz URL, podaj adres URL specyfikacji OpenAPI.
7. Kliknij Importuj, aby zaimportować go do modelu.
8. Nastąpi przekierowanie na stronę z informacjami o modelu, na której możesz go wyrenderować.

Ręczne tworzenie zasobów i metod

Jeśli nie masz pliku WADL lub specyfikacji OpenAPI, która reprezentuje Twój interfejs API, możesz ręcznie dodać do modelu interfejsy API. Jeśli do utworzenia modelu użyjesz pliku WADL lub specyfikacji OpenAPI, możesz skorzystać z tej procedury, aby edytować interfejsy API, w tym dodać nowe interfejsy API po imporcie.

Aby ręcznie dodać interfejs API:

1. Utwórz nową wersję modelu.
   
   Podczas tworzenia wersji określasz jedną ścieżkę bazową wszystkich interfejsów API w modelu, co oznacza, że wszystkie interfejsy API w modelu mają tę samą ścieżkę bazową. Podaj na przykład ścieżkę bazową jako:
   
   https://myCompany.com/v1
   
   Gdy dodajesz zasoby do modelu, rozszerzają one ścieżkę podstawową.
2. Zdefiniuj co najmniej 1 zasób modelu. Ścieżka zasobu łączy się ze ścieżką bazową wersji modelu, aby określić pełny adres URL zasobu. Jeśli na przykład zasób określa ścieżkę „/login”, pełny adres URL zasobu będzie wyglądał tak:
   
   https://myCompany.com/v1/login
3. Zdefiniuj co najmniej 1 metodę dla każdego zasobu. Metoda określa czasownik HTTP, który można wywołać w zasobie. Na przykład w przypadku zasobu „/login” możesz obsługiwać metodę POST (logowanie) i DELETE (wylogowanie). Ten zasób nie obsługuje innych czasowników HTTP, takich jak PUT czy GET. Zdefiniuj więc 2 metody dla zasobu: jedną dla metody POST, a drugą dla metody DELETE.
   
   Metoda korzysta z adresu URL zasobu ze swojego zasobu nadrzędnego. Dlatego wszystkie metody z tym samym adresem URL są zdefiniowane w jednym zasobie w SmartDokumentach.

Ogólna zasada:

• Utwórz inny model SmartDokumentacja dla każdej unikalnej ścieżki podstawowej w interfejsie API.
• Zdefiniuj inny zasób SmartDokumentacja dla każdego unikalnego zasobu w interfejsie API.
• Zdefiniuj inną metodę SmartDokumentacja dla każdego czasownika HTTP obsługiwanego przez zasób.

Tworzenie nowej wersji modelu

Zasób możesz dodać tylko do istniejącej wersji modelu. Jeśli model ma już wersję, możesz dodać zasób. Jeśli model jest nowy i nie ma żadnych wersji, utwórz nową wersję.

Aby utworzyć nową wersję modelu:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. W przypadku modelu, który chcesz zaktualizować, w sekcji Operacje wybierz Dodaj wersję.
4. Na stronie Dodaj wersję interfejsu API wpisz te informacje:
   • Display Name (Nazwa wyświetlana): nazwa wersji wyświetlana w portalu.
   • Identyfikator wersji: krótki identyfikator wersji.
   • Opis: opis wersji.
   • Podstawowy URL: podstawowy adres URL wszystkich interfejsów API w wersji modelu. Model może używać różnych podstawowych adresów URL dla każdej wersji. Możesz na przykład dodać wskaźnik wersji w podstawowym adresie URL. W pierwszej wersji modelu podstawowy adres URL to:
     https://myCompany.com/v1
     W następnej wersji podstawowy adres URL może wyglądać tak:
     https://myCompany.com/v2
5. Wybierz Dodaj wersję. Nastąpi przekierowanie na stronę wersji modelu. Możesz teraz definiować zasoby w modelu.

Definiowanie zasobu

Zasób określa pełny adres URL interfejsu API. Podczas definiowania zasobu określasz ścieżkę zasobu, która jest łączona z podstawowym adresem URL w wersji modelu, aby utworzyć pełny adres URL zasobu.

Aby zdefiniować zasób:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. Dla modelu, który chcesz zaktualizować, w sekcji Operacje wybierz Wersje interfejsu API, aby wyświetlić wszystkie wersje modelu.
4. Wybierz wersję do edycji.
5. Na stronie wersji wybierz z menu Dodaj zasób.
6. Na stronie Dodaj zasób podaj te informacje:
   • Wyświetlana nazwa: nazwa zasobu.
   • Ścieżka: ścieżka zasobu zaczynająca się od znaku „/”. Wartość pola Ścieżka jest połączona z podstawowym adresem URL wersji modelu, aby utworzyć pełny adres URL zasobu.
   • Opis: opis zasobu.
   • Parametry: opcjonalnie wpisz obiekt JSON definiujący każdy parametr w zasobie. Parametry te zostały opisane poniżej.
7. Wybierz Dodaj zasób. Nastąpi przekierowanie na stronę modelu. Możesz teraz zdefiniować metody dla zasobu.

Opcjonalnie możesz dodać do zasobu parametry, takie jak parametry szablonu, zapytania i nagłówka. Wszystkie parametry zasobów są dziedziczone przez dowolne metody zdefiniowane w tym zasobie. Dlatego, jeśli zdefiniujesz parametr zapytania dla zasobu, wszystkie metody dodane do tego zasobu muszą obsługiwać ten parametr zapytania.

Możesz też zdefiniować parametry metody. Na przykład metoda POST może obsługiwać parametry zapytania, które nie są obsługiwane przez metodę DELETE. Dlatego podczas jej definiowania dodaj dowolne parametry specyficzne dla metody w sposób opisany poniżej.

Poniższy obraz przedstawia istniejącą stronę SmartDokumentacja dla interfejsu API Apigee Approve or Unsubscribe Developer App z wyróżnionymi typami parametrów:

Każdy typ parametru jest definiowany przez obiekt JSON:

Parametr szablonu definiuje zmienną na ścieżce zasobu. Możesz na przykład zdefiniować 2 parametry szablonu dla zasobu. Zwróć uwagę, że każda definicja parametrów w tablicy parametrów jest rozdzielona przecinkami:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Następnie możesz użyć parametrów szablonu w definicji ścieżki zasobu w klamrze „{}”. Na przykład ustaw ścieżkę:

/login/{org_name}/{developer_email}

Na stronie interfejsu SmartDokumentacja API użytkownik musi zmodyfikować adres URL, aby określić fragment adresu URL org_name i developer_email, przed przesłaniem prośby.

Definiowanie metody

Zdefiniuj co najmniej 1 metodę dla każdego zasobu. Definicja metody określa czasownik HTTP, który można wywołać z poziomu zasobu. Zasób może mieć zdefiniowaną jedną metodę lub wiele metod.

W ramach definiowania metody określ wszystkie parametry, których ona używa, w tym parametry zapytania i nagłówka. Informacje na temat dodawania parametrów do metody znajdziesz w opisie powyżej.

Poniższy przykład przedstawia istniejącą stronę SmartDokumentacja dla interfejsu Apigee Create Developer API, w której każdy obszar strony jest wyróżniony odpowiednią wartością ustawioną podczas definiowania metody:

Następny obraz przedstawia tę samą stronę, ale z wybranym opisem treści żądania:

Aby zdefiniować metodę:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. Dla modelu, który chcesz zaktualizować, w sekcji Operacje wybierz Wersje interfejsu API, aby wyświetlić wszystkie wersje modelu.
4. Wybierz wersję do edycji.
5. Na stronie wersji wybierz z menu jednego z zasobów Add Method (Dodaj metodę).
6. Na stronie Edit Method (Metoda edycji) wpisz te informacje:
   • Wyświetlana nazwa: nazwa interfejsu API, która staje się też tytułem strony interfejsu API w Drupal.
   • Opis: opisz interfejs API.
   • Metoda Verb: typ czasownika HTTP.
   • Schematy zabezpieczeń: określ tryb uwierzytelniania (jeśli jest włączony) dla metody. Więcej informacji znajdziesz w artykule Konfigurowanie typu uwierzytelniania SmartDokumentacja.
   • Typ treści: typ treści żądania i odpowiedzi. Informacje o konfigurowaniu różnych metod uwierzytelniania znajdziesz w sekcji poniżej.
   • Parameters (Parametry): (opcjonalne) dowolne parametry zapytania lub nagłówka danej metody. Więcej informacji o dodawaniu parametru do zasobu znajdziesz w opisie powyżej.
   • Request Body Dokumentacja: (opcjonalnie) opisz treść żądania. Metody POST i PUT przyjmują treść żądania. Możesz w tym obszarze go opisać. Jeśli pominiesz tę wartość, link Opis w sekcji Treść żądania zostanie pominięty na wygenerowanej stronie Dokumentów Smart.
   • Przykład treści żądania: (opcjonalnie) pokaż przykładową treść żądania, zwykle w postaci obiektu JSON lub XML. W przypadku czasowników POST i PUT w ramach każdego żądania przekazywany jest przykład treści żądania. Użytkownicy strony SmartDokumentacja edytują ten przykład, zanim prześlą żądanie do interfejsu API. Jeśli pominiesz tę wartość, link Wartość w sekcji Treść żądania zostanie pominięty na wygenerowanej stronie Dokumentów Smart Docs.
   • Tagi: tablica tagów powiązanych z interfejsem API. SmartDokumentacja wykorzystuje tagi do grupowania podobnych interfejsów API. Możesz na przykład zastosować tag „Statystyki” do wszystkich interfejsów API związanych ze statystykami. Interfejsy API z różnych zasobów możesz zgrupować w jednym tagu, jeśli wszystkie używają tego samego tagu.
7. Wybierz Add Method (Dodaj metodę). Nastąpi przekierowanie na stronę modelu. Możesz teraz wyrenderować i opublikować swoją metodę.

Renderowanie modelu

Po dodaniu do modelu interfejsów API możesz go wyrenderować. Renderowanie konwertuje opis interfejsu API modelu na węzły Drupal. Po zakończeniu renderowania będziesz mieć 1 węzeł Drupal dla każdego interfejsu API, gdzie każdy węzeł Drupal odpowiada stronie HTML.

Możesz od razu wyrenderować cały model lub wybrać poszczególne interfejsy API do renderowania.

Aby wyrenderować model:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. W przypadku modelu, który chcesz renderować, w sekcji Operacje wybierz Wersje interfejsu API.
4. Wybierz wersję, którą chcesz wyrenderować. Węzły można renderować tylko z 1 wersji modelu.
5. Wybierz metody renderowania.
6. Wybierz Węzły renderowania w menu Opcje aktualizacji.
7. Kliknij Aktualizuj.
8. Pojawi się ekran wczytywania, na którym możesz obserwować postęp renderowania węzłów.
   Po wyrenderowaniu węzłów identyfikator węzła Drupal dla każdego interfejsu API pojawi się w kolumnie Powiązanie węzłów modelu. Kliknij link w kolumnie Powiązanie węzła, aby wyświetlić wyrenderowany węzeł.

Zamiast wybierać Węzły renderowania, możesz wybrać Renderuj i opublikuj węzły, aby wyrenderować i od razu opublikować interfejsy API jako węzeł Drupal.

Węzły publikowania

Węzeł nie jest widoczny dla użytkowników portalu, dopóki nie zostanie opublikowany. Opcjonalnie możesz opublikować węzły podczas procesu renderowania. Jeśli zdecydujesz się nie publikować węzłów, musisz je opublikować ręcznie po zakończeniu renderowania.

Aby opublikować węzeł:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. W sekcji Operacje wybierz Wersje interfejsu API dla modelu, który chcesz opublikować.
4. Wybierz wersję, którą chcesz opublikować. Węzły można publikować tylko z jednej wersji modelu.
5. Wybierz metody publikowania.
6. Wybierz węzły w wersji do opublikowania.
7. Z menu Opcje aktualizacji wybierz Opublikuj węzły.
8. Kliknij Aktualizuj.
9. Przejdź do węzła, wybierając jego identyfikator w kolumnie Powiązanie węzłów.

Domyślnie adres URL platformy Drupal do opublikowanego węzła interfejsu API ma postać: http://<drupalBasePath>/<nazwa_wewnętrzna>/apis/<httpMethod>/<resourcePath>. Aby określić formę adresu URL, skorzystaj z poniższej procedury:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administrowania Drupal wybierz Konfiguracja > Wyszukiwanie i metadane > Aliasy adresów URL > Wzorce.
3. W sekcji Wzorzec dla wszystkich ścieżek metody SmartDokumentacja określ sposób generowania ścieżki.
4. Wybierz Zapisz konfigurację.

Ze względu na buforowanie w portalu strony modeli mogą nie pojawiać się od razu po ich opublikowaniu. W razie potrzeby możesz ręcznie wyczyścić pamięć podręczną HTML SmartDokumentacja, wykonując następującą procedurę:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administrowania Drupal wybierz Konfiguracja > SmartDokumenty.
3. Kliknij Utwórz ponownie pamięci podręczne modeli SmartDokumentów.

Cofanie publikacji węzła

W każdej chwili możesz cofnąć publikację węzła. Cofnięcie publikacji węzła sprawia, że jest on niewidoczny dla użytkowników portalu.

Aby cofnąć publikację węzła:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDocuments w menu administrowania Drupal.
3. W sekcji Operacje wybierz Wersje interfejsu API dla modelu, który chcesz cofnąć publikację.
4. Wybierz wersję modelu węzła, którą chcesz cofnąć publikację.
5. Wybierz węzły w wersji, których publikację chcesz cofnąć.
6. Z menu Opcje aktualizacji wybierz Cofnij publikację węzłów.
7. Kliknij Aktualizuj.

Wyświetlanie wersji modelu

Nową wersję modelu możesz utworzyć, importując nowy plik WADL lub specyfikację OpenAPI do istniejącego modelu, albo ręcznie tworząc nową wersję. Po utworzeniu nowej wersji możesz ją wyrenderować i opublikować, co zastąpi obecnie opublikowane węzły Drupal.

Możesz renderować i publikować węzły z wielu wersji jednocześnie. Oznacza to, że jeśli masz 5 wersji modelu, możesz publikować węzły z dowolnej lub ze wszystkich wersji. Jednak opublikowanie w jednym modelu interfejsu API, który jest taki sam jak opublikowany węzeł w innym modelu, spowoduje cofnięcie publikacji starszej wersji interfejsu API i zastąpienie go wersją z ostatnio opublikowanego interfejsu API.

Aby wyświetlić wersję modelu:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > Inteligentne dokumenty w menu administrowania Drupal.
3. W sekcji Operacje wybierz Wersje interfejsu API dla modelu, który chcesz zaktualizować.
4. Wybierz wersję modelu, którą chcesz wyświetlić.
5. Renderuj i opublikuj węzły w sposób opisany powyżej.

Edytowanie węzła

Po wyrenderowaniu węzła możesz go edytować za pomocą edytora Drupal. Możesz na przykład edytować czasownik HTTP i opis interfejsu API lub dodać do niego nowy parametr zapytania lub nagłówka. Możesz edytować węzły utworzone za pomocą pliku WADL lub specyfikacji OpenAPI albo węzłów utworzonych ręcznie.

Możesz też edytować oryginalny plik WADL lub specyfikację OpenAPI. Po zakończeniu edycji zaimportuj plik WADL lub specyfikację OpenAPI z powrotem do modelu jako nową wersję, a następnie wyrenderuj i opublikuj zmiany w sposób opisany powyżej.

Aby edytować węzeł za pomocą edytora Drupal:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Przejdź do węzła Drupal odpowiadającego dokumentacji interfejsu API, którą chcesz edytować.
3. Aby użyć edytora Drupal, kliknij Edytuj.
4. Po wprowadzeniu zmian wybierz Update Method (Metoda aktualizacji).

Możesz też edytować węzeł z poziomu modelu SmartDokumentacja:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > Inteligentne dokumenty w menu administrowania Drupal.
3. W sekcji Operacje wybierz Wersje interfejsu API dla modelu, który chcesz zaktualizować.
4. Wybierz wersję modelu, którą chcesz opublikować.
5. W menu Operacje wybierz Edytuj metodę dla metody, którą chcesz edytować.

Aby usunąć węzeł:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > Inteligentne dokumenty w menu administrowania Drupal.
3. W sekcji Operacje wybierz Wersje interfejsu API dla modelu, który chcesz zaktualizować.
4. Wybierz wersję modelu, którą chcesz opublikować.
5. W menu Operacje wybierz Usuń metodę dla tej metody.
   Uwaga: usunięcie węzła spowoduje też usunięcie interfejsu API z modelu. Jeśli chcesz tylko cofnąć publikację interfejsu API, tak aby był ukryty dla użytkowników portalu, a nie chcesz usuwać go z modelu, cofnij publikację węzła w sposób opisany powyżej.

Portal ma wbudowany raport, który wyświetla informacje o każdym węźle renderowanym przez model SmartDokumentacja, który nie odnosi się już do prawidłowych metod modelu. Aby otworzyć raport, wybierz Raporty w menu Drupal, a następnie wybierz raport o nazwie Stan węzła SmartDokumentacja.

Eksportowanie i importowanie modelu

SmartDokumenty umożliwiają wyeksportowanie istniejącego modelu do pliku. Możesz na przykład zdefiniować środowisko produkcyjne i przejściowe. Następnie wszystkie zmiany w inteligentnych Dokumentach wprowadzasz w środowisku przejściowym. Gdy wszystko będzie gotowe do opublikowania interfejsów API, wyeksportuj model przejściowy i zaimportuj go do modelu produkcyjnego.

Zaimportowanie modelu powoduje utworzenie jego nowej wersji. SmartDokumentacja próbuje dopasować istniejące interfejsy API w modelu do zaimportowanych interfejsów API. Jeśli SmartDokumentacja wykryje dopasowanie, import aktualizuje węzeł Drupal odpowiadający istniejącemu interfejsowi API. Jeśli SmartDokumentacja nie wykryje dopasowania, import tworzy nowy węzeł Drupal dla interfejsu API.

Na przykład masz interfejs API POST odpowiadający węzłowi Drupal o identyfikatorze 91. Następnie zaimportuj model, a aplikacja SmartDokumentacja wykryje dopasowanie interfejsu API POST w zaimportowanym modelu do istniejącego interfejsu POST API. Wszelkie zmiany w interfejsie POST API zaktualizują węzeł Drupal 91. Jeśli SmartDokumentacja nie wykryje dopasowania, utworzy nowy węzeł Drupal z nowym identyfikatorem.

Drupal przeprowadza dopasowanie, korzystając z tych elementów interfejsu API:

• internalName: wewnętrzna nazwa modelu.
• httpMethod: metoda HTTP interfejsu API, np. GET, PUT, POST lub DELETE.
• resourcePath: ścieżka zasobu.
• query params: dowolne parametry zapytania używane przez interfejs API.

Jeśli wszystkie 4 cechy zaimportowanego interfejsu API pasują do istniejącego interfejsu API w modelu, SmartDokumentacja aktualizuje istniejący węzeł Drupal.

Wyeksportowany model jest reprezentowany przez pojedynczy obiekt JSON z wpisami dla zasobów i metod. Oznacza to, że możesz zmodyfikować wyeksportowany model, aby zmodyfikować zasób lub metodę, a następnie ponownie go zaimportować. Jeśli edytujesz obiekt JSON, nie zmieniaj tych pól:

• revisionNumber
• createdTime
• modifiedTime
• apiRevisionId
• resourceId

Aby wyeksportować model:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. W przypadku modelu, który chcesz wyeksportować, w sekcji Operacje wybierz Eksportuj.
4. Jako typ pliku eksportu wybierz SmartDokumentacja JSON.
5. Kliknij Eksportuj.
6. Pojawi się prośba o zapisanie pliku na dysku lub otwarcie go w edytorze.

Aby zaimportować model:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > SmartDokumentacja w menu administrowania Drupal.
3. W przypadku modelu, który chcesz zaimportować, w sekcji Operacje wybierz Importuj.
4. W menu Wybierz format wybierz Smart Docs JSON.
5. W polu Typ przesyłania wybierz Plik lub URL:
   1. Jeśli wybierzesz Plik, przejdź do pliku JSON.
   2. Jeśli wybierzesz URL, podaj adres URL pliku JSON SmartDokumentacja.
6. Kliknij Importuj, aby zaimportować go do modelu.
7. Nastąpi przekierowanie na stronę z informacjami o modelu, na której możesz go wyrenderować. Pamiętaj, że import tworzy nową wersję modelu.
8. Wyrenderuj i opublikuj węzły.

Edytowanie szablonu Inteligentne dokumenty

Szablon SmartDokumentów określa sposób wyświetlania węzłów Drupal na ekranie. Każdy model SmartDokumentów może używać tego samego szablonu domyślnego. Możesz też ręcznie dostosować szablon używany w poszczególnych modelach.

Szablon SmartDokumentacja zawiera plik szablonu zakodowany jako plik .hbr z uchwytami oraz pliki CSS i JavaScript. W przypadku uchwytów znaczna część treści jest określana na podstawie zmiennych za pomocą osadzonych wyrażeń dotyczących uchwytów, takich jak &123;&123;body}}. Listę istniejących wyrażeń na pasku nawigacyjnym znajdziesz w komentarzu u góry pliku. Więcej informacji o dostosowywaniu szablonów za pomocą uchwytów znajdziesz na http://handlebarsjs.com.

W poniższych sekcjach opisano, jak przesłać niestandardowy plik szablonu SmartDokumentów do użytku przez wszystkie nowe modele lub podczas importowania nowych interfejsów API do istniejącego modelu, jak przywrócić oryginalny domyślny plik szablonu SmartDokumentacja oraz jak zmodyfikować szablon SmartDokumentacja w konkretnym modelu.

Przesyłanie niestandardowego pliku szablonu SmartDokumentów

Niestandardowy plik szablonu SmartDokumentów możesz przesłać jako plik .hbr z uchwytami, aby używać go jako domyślnego szablonu podczas tworzenia nowych modeli lub importowania nowych interfejsów API do istniejącego modelu.

Jeśli chcesz użyć domyślnego pliku szablonu SmartDokumentacja jako punktu wyjścia przy tworzeniu niestandardowego pliku szablonu SmartDokument, możesz pobrać kopię z: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Aby przesłać niestandardowy plik szablonu SmartDokumentów:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administrowania Drupal wybierz Konfiguracja > SmartDokumentacja.
3. Rozwiń obszar Ustawienia zaawansowane.
4. W sekcji „Prześlij szablon metody niestandardowego” kliknij Wybierz plik i przejdź do pliku .hbr z uchwytami.
5. Kliknij Prześlij.
6. Kliknij Save setup (Zapisz konfigurację).

Przywracam domyślny plik szablonu SmartDokumentacja

Możesz przywrócić domyślny plik szablonu SmartDokumentacja. Po przywróceniu domyślny plik szablonu SmartDokumentacja będzie używany podczas tworzenia nowych modeli lub importowania nowych interfejsów API do istniejącego modelu.

Aby przywrócić domyślny plik szablonu SmartDokumentacja:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. W menu administrowania Drupal wybierz Konfiguracja > SmartDokumentacja.
3. Rozwiń obszar Ustawienia zaawansowane.
4. W sekcji Prześlij niestandardowy szablon metody kliknij Usuń obok pliku niestandardowego szablonu SmartDokumentów.
5. Kliknij Save setup (Zapisz konfigurację).

Modyfikowanie szablonu SmartDokumentów w pojedynczym modelu

Możesz modyfikować szablony używane w poszczególnych modelach.

Aby zmodyfikować szablon dla pojedynczego modelu:

1. Zaloguj się w portalu jako użytkownik z uprawnieniami administratora lub z uprawnieniami do tworzenia treści.
2. Wybierz Treść > Inteligentne dokumenty w menu administrowania Drupal.
3. W przypadku modelu, który chcesz edytować, w sekcji Operacje wybierz Ustawienia.
4. W razie potrzeby w obszarze Szablon metody edytuj szablon.
5. Kliknij Zapisz szablon.
6. Przejdź do węzła Drupal. Zmiany w szablonie powinny się wyświetlić na stronie.

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>