发现 REST API 文档

从 WebSphere® Application Server Traditional 9.0.0.1开始，您可以发现并公开已部署的 RESTful 端点的 Swagger 文档。您还可以使用内置 Swagger 用户界面来调用 API。

有关此任务

发现已部署的 RESTful 端点的 Swagger 文档，并使用该接口来调用 API。

过程

如果在 Deployment Manager 环境中使用定制概要文件，请安装 Swagger 应用程序并将其映射到在定制概要文件上运行的应用程序服务器。如果使用应用程序服务器概要文件或非 Deployment Manager 环境，请跳过此步骤。
1. 运行 deploySwaggerUI 脚本以将 Swagger 应用程序安装到目标上。
  1. 将 user_name 和 user_password 更改为相应的值。目标必须是最后一个参数，并用双引号括起。请参阅 deploySwaggerUI 脚本的以下示例调用:
```
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 发现，请从单元中除去这两个应用程序。
```
wsadmin -user user_name -password user_password -f deploySwaggerUI.py remove 
```
使用管理控制台或 wsadmin AdminConfig.modify 命令启用 API 发现服务。
- 使用管理控制台来启用 API 发现服务。
  1. 单击服务器 > 服务器类型 > WebSphere Application Server > server_name > Web 容器设置 > Web 容器。
  2. 选择启用 API 发现服务。
  3. 保存更改并重新启动服务器以使更改生效。
  有关更多信息，请参阅 Web 容器设置。
- 使用 wsadmin 脚本编制来启用 API 发现服务。
  1. 运行 AdminConfig.modify 命令。将 ${CELL}， ${NODE}和 ${SERVER} 替换为相应的值。
```
AdminConfig.modify('(cells/${CELL}/nodes/${NODE}/servers/${SERVER}|server.xml
#WebContainer_1183122130078)', '[ [apiDiscovery "true"] ]')
```
  2. 重新启动服务器以使更改生效。
  有关更多信息，请参阅使用 wsadmin 脚本编制的 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 注释，请参阅 Package 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 以接收仅包含有关来自 /airlines Web 模块的端点的信息的 Swagger 文档。
- Swagger UI 资源管理器
  1. 打开浏览器并浏览至 https://host:https_port/ibm/api/explorer。
  2. 调用 /ibm/api/docs 以接收用户界面。单击试用以浏览并调用各种端点。