Generowanie dokumentacji interfejsu API usług REST za pomocą interfejsu OpenAPI

Dokumentację interfejsu API usług REST można wygenerować za pomocą funkcji openapi-3.0 , która obsługuje specyfikację OpenAPI . Należy udokumentować interfejsy API usług REST, określić publiczne i prywatne interfejsy API, wybrać opcję włączenia skanowania adnotacji i wdrożyć aplikacje WWW na serwerze Liberty . Następnie można wyświetlić dokumentację interfejsu API, która jest generowana przez program openapi-3.0 w przeglądarce, która korzysta z interfejsu użytkownika przyjaznego dla człowieka.

Stabilizowane funkcje: Funkcje OpenAPI V3 , openapi-3.0 i openapi-3.1, są stabilne. Można nadal korzystać z funkcji. Alternatywą strategiczną jest jednak użycie funkcji MicroProfile OpenAPI , takiej jak mpOpenAPI-3.0.

Open Liberty Więcej informacji na temat używania programu MicroProfile OpenAPI z produktem Libertyzawiera sekcja Serwis WWW Otwórz Liberty

Zanim rozpoczniesz

Sekcja zawiera informacje na temat specyfikacji OpenAPI V3. Do dokumentowania interfejsów API RESTful w aplikacjach używane są pliki YAML lub JSON.

Można użyć interfejsów Java i modeli programistycznych, które są dostępne w Specyfikacja MicroProfile OpenAPI w wersji 1.0. Składnik mpOpenAPI-1.0 implementuje specyfikację MicroProfile OpenAPI . Więcej informacji na temat opcji mpOpenAPI-1.0 i nowszych funkcji zawiera sekcja Generowanie dokumentacji interfejsu API usług REST za pomocą interfejsu MicroProfile OpenAPI.

Informacje o tej czynności

Te funkcje, takie jak nowy interfejs użytkownika, adnotacje i interfejsy programistyczne, można eksplorować przy użyciu następujących przykładowych aplikacji.

Spróbuj udokumentować aplikację zgodną ze specyfikacją REST za pomocą adnotacji OpenAPI w kodzie Java™ przy użyciu przykładowej aplikacji OpenAPI V3 adnotacji.
Przykład dokumentu OpenAPI V3 w formacie YAML utworzonego za pomocą edytora tekstu z przykładowym dokumentem OpenAPI V3.
Rozszerzanie składnika openapi-3.0 przy użyciu interfejsów programistycznych produktu io.swagger.oas.integration.OpenAPIConfigurationBuilder za pomocą interfejsu programistycznego OpenAPIConfiguration.

Procedura

Buduj dokumentację OpenAPI .
Dokumenty OpenAPIs można dokumentować i budować na kilka sposobów:
- Określ adnotacje OpenAPI w kodzie Java, aby rozszerzyć i udokumentować aplikację.
- Użyj edytora tekstu, aby udokumentować interfejs API za pomocą znaczników OpenAPI , a następnie umieść wypełniony plik openapi.yaml, openapi.ymllub openapi.json w katalogu META-INF aplikacji.
- Za pomocą interfejsów programistycznych produktu io.swagger.oas.integration.OpenAPIConfigurationBuilder można zbudować model OpenAPI z poziomu aplikacji. Interfejs ten oraz inne powiązane interfejsy programistyczne dla OpenAPI V3można znaleźć w plikach JAR w katalogu /wlp/dev/api/third-party . Aby program openapi-3.0 uruchamiał program budujący OpenAPIConfiguration, archiwum aplikacji musi mieć plik META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder . Treść tego pliku jest pełną nazwą programu budującego OpenAPIConfiguration.
  Więcej informacji na temat dostępnych interfejsów programistycznych, opisy ich możliwości oraz przykłady ich użycia zawiera sekcja Interfejsy programistyczne produktu OpenAPI V3.
Włącz opcję openapi-3.0 w konfiguracji serwera Liberty .
1. Dodaj składnik openapi-3.0 do menedżera składników.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Opcjonalnie: Określ, że aplikacja OpenAPI jest prywatna.
  
  Domyślnie dokumentacja OpenAPI jest publiczna. Wszyscy użytkownicy mogą uzyskiwać dostęp do publicznych interfejsów API, często bez uwierzytelniania. Publiczne interfejsy API są udokumentowane w zasobie /api/docs .
  Można określić, że interfejsy API mają pozostać prywatne. Interfejsy API do użytku administracyjnego są zwykle przechowywane jako prywatne. Prywatne interfejsy API, które używają haseł do ochrony, są udokumentowane w zasobie /ibm/api/docs . Ten zasób dokumentuje wszystkie prywatne interfejsy API i wszystkie publiczne interfejsy API.
  
  Prywatne interfejsy API dla aplikacji WWW można określić na dwa sposoby:
  - Użyj opcji webModuleDoc w konfiguracji serwera, z atrybutem public ustawionym na wartość false.
    1. Dodaj element openapi i ustaw jego atrybut boolowski enablePrivateURL na wartość true.
    2. Dodaj podelement webModuleDoc dla każdej aplikacji WWW i ustawia jego atrybut boolowski public na wartość true dla publicznych interfejsów API i false dla prywatnych interfejsów API.
    Poniższy przykład sprawia, że aplikacja linii lotniczych OpenAPIs jest widoczna i wyłącza ekspozycję aplikacji airlinesAdmin OpenAPIs.
```
<openapi enablePrivateURL="true">
  <webModuleDoc contextRoot="/airlines" public="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
```
    Domyślnie atrybut public produktu webModuleDoc jest ustawiony na wartość true. Ta konfiguracja jest wymagana tylko w celu wyłączenia aplikacji, które mają być prywatne.
  - Użyj słowa kluczowego rozszerzenia dostawcy w opisie interfejsu API, aby wskazać, że interfejs API jest prywatny.
    1. Dodaj element openapi do konfiguracji serwera i ustaw jego atrybut boolowski enablePrivateURL na wartość true.
    2. Umieść słowo kluczowe x-ibm-private: true i wartość w pliku opisu funkcji API META-INF/openapi.yaml lub w pliku innego obsługiwanego formatu. Ta wartość przesłania domyślną widoczność interfejsu API, a ta wartość może zostać przesłonięta przez pozycję webModuleDoc .
3. Opcjonalnie: Określ, że aplikacja nie jest wyświetlana w dokumencie OpenAPI .
  
  Domyślnie moduły WWW, które zawierają dokumenty interfejsu API REST, są wyświetlane w scalonym dokumencie OpenAPI dostępnym w zasobie /api/docs . Aby moduły WWW były wyświetlane z poziomu dokumentu OpenAPI , należy zmienić atrybuty elementu webModuleDoc w konfiguracji serwera.
  Zidentyfikuj moduł WWW, który ma zostać ukryty lub wyświetlony z atrybutem contextRoot . Następnie należy zmienić atrybut enabled na wartość false , aby ukryć moduł WWW z dokumentu OpenAPI . Wartością domyślną atrybutu enabled jest true. W poniższym przykładzie moduł linii lotniczych jest skonfigurowany w taki sposób, że jest on wyświetlany w dokumencie OpenAPI , a moduł airlinesAdmin jest ukryty.
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  Uwaga: Atrybut enabled nie jest obsługiwany w przypadku dokumentów interfejsu API usług REST, które są dostarczane przez inne funkcje Liberty .
Opcjonalnie: Włącz skanowanie adnotacji JAX-RS.

Dodaj składnik jaxrs-2.0 do menedżera składników. Jeśli na serwerze są włączone opcje jaxrs-2.0 i openapi-3.0 , skaner adnotacji skanuje wszystkie aplikacje WWW wdrożone na serwerze, chyba że konfiguracja serwera wyłączy skanowanie. Skaner przechodzi przez klasy, które są opatrzone adnotacjami OpenAPI 3.0 w definicji klasy i są opatrzone adnotacjami @Path JAX-RS. Dostęp do wygenerowanych dokumentów OpenAPI można uzyskać za pomocą publicznego punktu końcowego OpenAPI (api/docs) i prywatnego punktu końcowego (ibm/api/docs).
Zezwalaj na widoczność funkcji API innych firm dla konkretnych aplikacji.
Aby włączyć ładowanie środowiska wykonawczego dla adnotacji, modelu i modelu programowania OpenAPI , należy włączyć widoczność interfejsu API innych firm dla konkretnej aplikacji.
1. Zdefiniuj atrybut apiTypeVisibility elementu classloader jako widoczność interfejsu API innej firmy. Dodaj element third-party do elementu classloader w pliku server.xml .
  
  Jeśli produkt classloader nie zostanie określony w taki sposób, aby zawierał third-party w programie apiTypeVisibility, zostanie użyta domyślna definicja spec, stablei ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Opcjonalnie: Włącz sprawdzanie poprawności dokumentów OpenAPI .

Możliwość sprawdzania poprawności jest domyślnie wyłączona. Po włączeniu sprawdzania poprawności każdy dokument OpenAPI , który jest udostępniany przez aplikację, jest sprawdzany w oparciu o ograniczenia zadeklarowane w specyfikacji OpenAPI V3 przez składnik openapi-3.0 . Jeśli openapi-3.0 znajdzie dokument OpenAPI , który nie jest poprawny, funkcja zgłasza błąd w dziennikach dla każdego naruszonego ograniczenia. Niepoprawny dokument jest wykluczony z zagregowanego dokumentu OpenAPI , który jest zwracany przez punkt końcowy api/docs . Aby włączyć sprawdzanie poprawności, należy ustawić atrybut validation na wartość true w pliku server.xml .
```
<openapi validation="true"/>
```
Wdróż aplikacje.
Wyświetl wygenerowany dokument interfejsu API w przeglądarce.
Wygenerowany dokument interfejsu API można znaleźć w punkcie końcowym /api/docs , korzystając z jednego z następujących adresów URL, w zależności od tego, czy interfejs API jest publiczny, czy prywatny.
- W przypadku publicznych interfejsów API innych niż SSL wyświetl dokument pod adresem http://Liberty_host:http_port/api/docs.
- W przypadku publicznych interfejsów API protokołu SSL wyświetl dokument pod adresem https://Liberty_host:https_port/api/docs.
- W przypadku prywatnych interfejsów API protokołu SSL wyświetl dokument pod adresem https://Liberty_host:https_port/ibm/api/docs.
Wskazówka: Domyślnie dwa punkty końcowe są dostępne dla serwera.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
Adresy URL dla publicznych punktów końcowych można dostosować za pomocą atrybutu publicURL w pliku server.xml . W poniższym przykładzie przedstawiono konfigurację w pliku server.xml w celu udostępnienia dokumentacji publicznej interfejsu API usług REST za pomocą produktu GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer.
```
<openapi publicURL="myAPI" />
```
Dokument OpenAPI jest generowany i agregowany między aplikacjami dla tego serwera Liberty . Domyślnie dokument jest w formacie YAML. Podczas wyświetlania dokumentacji za pomocą programu Microsoft Internet Explorer 11 zwracany jest dokument YAML, który nie jest poprawnie sformatowany. Aby obejść ten problem, należy użyć przeglądarki, takiej jak Mozilla Firefox lub przeglądarki Google Chrome. Jeśli żądanie http ma nagłówek Accept z wartością application/json , dokument jest w formacie JSON.

Wskazówka: Dokument OpenAPI można filtrować według kontekstowego katalogu głównego. Zarówno publiczny punkt końcowy (api/docs), jak i prywatny punkt końcowy (ibm/api/docs) obsługują parametr zapytania root, który może filtrować wyszukane kontekstowe katalogi główne. Na przykład wywołanie funkcji GET http://Liberty_host:http_port/api/docs?root=/myApp pobiera dokument OpenAPI V3 , który zawiera tylko dokumentację dla kontekstowego katalogu głównego produktu myApp .

Wyniki

Interfejs użytkownika OpenAPI renderuje zagregowane definicje z produktu /api/docs w celu wyświetlenia interfejsu użytkownika przyjaznego dla człowieka w produkcie http://Liberty_host:http_port/api/explorer. Jeśli zostanie włączony protokół SSL, można uzyskać dostęp do chronionego interfejsu użytkownika w produkcie https://Liberty_host:https_port/api/explorer.

Istnieje możliwość przeglądania prywatnych modułów WWW przez włączenie atrybutu enablePrivateURL w elemencie openAPI pliku server.xml .

<openapi enablePrivateURL="true"/>

Gdy przeglądanie prywatnego modułu WWW jest włączone, należy użyć produktu https://Liberty_host:https_port/ibm/api/explorer w celu wyświetlenia interfejsu użytkownika przyjaznego dla użytkownika zarówno dla publicznych, jak i prywatnych modułów WWW.

W tym interfejsie użytkownika można wyświetlić wszystkie punkty końcowe RESTful z aplikacji. Możliwe jest również filtrowanie wyświetlanych punktów końcowych w celu skupienia się na konkretnych aplikacjach.