探索 REST API 文件

從 WebSphere® Application Server Traditional 9.0.0.1開始，您可以探索並公開已部署 RESTful 端點的 Swagger 文件。您也可以使用內建 Swagger 使用者介面來呼叫 API。

關於此作業

探索您已部署的 RESTful 端點的 Swagger 文件，並使用介面來呼叫 API。

程序

如果您在部署管理程式環境中使用自訂設定檔，請將 Swagger 應用程式安裝並對映至在自訂設定檔上執行的應用程式伺服器。如果您使用應用程式伺服器設定檔或部署管理程式環境以外的其他項目，請跳過此步驟。
1. 執行 deploySwaggerUI Script ，將 Swagger 應用程式安裝至目標。
  1. 將 user_name 和 user_password 變更為適當的值。目標必須是最後一個參數，並以雙引號括住。請參閱下列 deploySwaggerUI Script 呼叫範例:
```
wsadmin -user user_name -password user_password -f deploySwaggerUI.py 
install "WebSphere:cell=cell01,node=node01,server=server1"
```
  2. 執行下列 wsadmin 指令，將應用程式對映至其他目標伺服器:
```
AdminApp.edit('SwaggerUI', '[ -MapModulesToServers [[ SwaggerUI SwaggerUI.war,WEB-INF/web.xml 
WebSphere:cell=cell01,node=node01,server=server1+WebSphere:cell=cell01,node=node02,server=server1 ]]]') 

AdminApp.edit('RESTAPIDocs', '[ -MapModulesToServers [[ RESTAPIDocs RESTAPIDocs.war,WEB-INF/web.xml 
WebSphere:cell=cell01,node=node01,server=server1+WebSphere:cell=cell01,node=node02,server=server1 ]]]')
 
AdminConfig.save()
```
2. 選用: 如果您不再想要啟用 API 探索，請從 Cell 中移除這兩個應用程式。
```
wsadmin -user user_name -password user_password -f deploySwaggerUI.py remove 
```
使用管理主控台或 wsadmin AdminConfig.modify 指令來啟用 API 探索服務。
- 使用管理主控台來啟用 API 探索服務。
  1. 按一下伺服器 > 伺服器類型 > WebSphere 應用程式伺服器 > server_name > Web 儲存器設定 > Web 儲存器。
  2. 選取啟用 API 探索服務。
  3. 儲存變更並重新啟動伺服器，讓變更生效。
  如需相關資訊，請參閱 Web 儲存器設定。
- 使用 wsadmin Scripting 來啟用 API 探索服務。
  1. 執行 AdminConfig.modify 指令。將 ${CELL}、 ${NODE}和 ${SERVER} 取代為適當的值。
```
AdminConfig.modify('(cells/${CELL}/nodes/${NODE}/servers/${SERVER}|server.xml
#WebContainer_1183122130078)', '[ [apiDiscovery "true"] ]')
```
  2. 重新啟動伺服器，讓變更生效。
  如需相關資訊，請參閱使用 wsadmin Scripting 的 AdminConfig 物件指令。
附註: 如果您在已啟用 SAF 授權的 WebSphere Application Server for z/OS® 上啟用 API 探索服務，您需要允許使用者或群組具有 allAuthenticatedUsers 角色才能存取它。
比方說，如果您想要允許 WebSphere 管理群組 (WSCFG) 成為 allAuthenticatedUsers角色，您可以使用這些指令。
```
RDEFINE EJBROLE allAuthenticatedUsers UACC(NONE)
PERMIT allAuthenticatedUsers CLASS(EJBROLE) ID(WSCFG) ACCESS(READ)
SETROPTS RACLIST(EJBROLE) REFRESH
```
文件 RESTful 端點。

最佳作法: 使用 Swagger 註釋來擴增現有的 JAX-RS 端點。如果您已安裝 JAX-RS (1.1 或 2.0) 應用程式，您可以跳過這個步驟，但 Swagger 註釋可讓您新增每一個端點的詳細資料。如需 Swagger 註釋，請參閱套件 io.swagger.annotations。
1. 如果要使用及編譯 Swagger 註釋，請將 app_server_root/dev/swagger/swagger-annotations-1.5.3.jar 新增至類別路徑。
  
  WebSphere Developer Tools 會自動將目錄新增至您的檔案路徑。
2. 新增產生的 swagger.json 或 swagger.yaml 檔案。
  - 若為 Servlet ，請在 Web 模組的 META-INF 資料夾內包含產生的 swagger.json 或 swagger.yaml 檔案。
  - 對於同時包含 JAX-RS 和 Servlet 的混合式 Web 模組，請在 Web 模組的 META-INF/stub 資料夾內包含產生的 swagger.json 或 swagger.yaml ，這會與 JAX-RS 部分所處理的註釋合併。
    如果您的應用程式使用不同於 default_host 的虛擬主機，或如果您要在 API 中記載負載平衡器，請在包含新 host:port的 Web 模組的 META-INF/stub 資料夾內包含最小 swagger.json 或 swagger.yaml 。請參閱下列範例：
    { "swagger": "2.0", "host": "virtualHost:3005" }
限制: 您可以公開 Java EE 應用程式 (例如 EAR 或 WAR) ，但無法公開 OSGi 應用程式 (EBA)。
檢視產生的文件及使用者介面瀏覽器。
- 聚集 Swagger 文件
  1. 開啟瀏覽器，並導覽至 https://host:https_port/ibm/api/explorer 以接收 JSON 格式的 Swagger 2.0 文件，其中包含 RESTful 端點的聚集文件。
  2. 將值為 application/yaml 的 Accept 新增至要求標頭，以 YAML 格式接收此文件。
  3. 使用多基數查詢參數 root 來過濾端點。例如，呼叫 /ibm/api/docs?root=/airlines 以接收 Swagger 文件，該文件只包含來自 /airlines Web 模組之端點的相關資訊。
- Swagger 使用者介面瀏覽器
  1. 開啟瀏覽器，並導覽至 https://host:https_port/ibm/api/explorer。
  2. 呼叫 /ibm/api/docs 以接收使用者介面。按一下試用，以導覽並呼叫各種端點。