在 Liberty 服务器上发现 REST API 文档
![[18.0.0.1 and later]](../ng_v18001plus.gif)
过程
- 在您要查找其可用 REST API 的 Liberty 服务器的 server.xml 文件中,将 apiDiscovery-1.0 功能部件添加至功能部件管理器。
apiDiscovery-1.0 功能部件在产品中启用 REST API 发现捆绑软件。此功能部件还会显示 JMX 之类的 Liberty REST 端点(如果服务器配置使用 restConnector-1.0 功能部件)和集合体(如果服务器配置使用 collectiveController-1.0 功能部件)中的文档。
Liberty 集合体控制器服务器上启用的 apiDiscovery-1.0 功能部件在控制器及其启用了 apiDiscovery-1.0 功能部件的成员服务器上查找可用的 REST API。
确保服务器配置具有所部署应用程序需要的所有功能部件,例如,jaxrs-2.0。修改端口,以便服务器可以打开其 HTTP 端口。
如果要显示专用 REST API 文档,请在 server.xml 文件中配置密钥库服务对象条目和用户注册表设置。
但是,如果希望仅显示公用 REST API 文档,那么只有在您希望通过 HTTPS 访问文档时,才添加密钥库对象条目。通过 HTTP 访问公共文档不需要密钥库对象条目和用户注册表设置。
以下 server.xml 文件具有 apiDiscovery-1.0 功能部件:
<server> <featureManager> <feature>apiDiscovery-1.0</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="8010" httpsPort="8020"/> <keyStore id="defaultKeyStore" password="Liberty"/> <basicRegistry id="basic" realm="ibm/api"> <user name="bob" password="bobpwd" /> </basicRegistry> </server>
- 显示 Liberty REST 端点中的 Swagger 2.0 文档。
如果 Web 应用程序包含 javax.ws.rs.core.Application 类的两个或更多实例,可正确地与 API 发现功能部件配合使用,那么每个应用程序都需要唯一 javax.ws.rs.@ApplicationPath 值或 web.xml 文件中定义的 url-mapping。
启用 apiDiscovery-1.0 功能部件以将当前文档与注释扫描期间找到的文档进行合并。产品在 Web 模块中搜索 META-INF/stub/swagger.json 或 META-INF/stub/swagger.yaml 文件。如果功能部件找到这两个文件其中的任何一个,那么它将生成包含文件内容以及 Web 模块中所有 JAX-RS 和 Swagger 注释的 Swagger 文档。可以使用此功能部件来记录非 JAX-RS servlet,因为该文档将自动与 JAX-RS 部分合并。可通过以下两种方式中的任何一种配置 API 文档的位置:
- 使用 SPI
com.ibm.wsspi.rest.api.discovery.APIProvider 接口的 getDocumentation 方法。
getDocument 方法允许扩展功能部件中的 OSGi 捆绑软件将 REST API 文档添加至整个主文档。对于此发行版,唯一受支持 DocType 为 DocType.Swagger_20_JSON 和 DocType.Swagger_20_YAML。此接口的实现者可将序列化 JSON 或 YAML 文档返回为 java.lang.String 值,或者可以将文件引用(带有前缀 file:///)传递至 JSON 或 YAML 文件位置。
- 使用所部署 Web 应用程序。
每个 Web 模块可继续自己的 REST API 文档。企业应用程序 (EAR) 文件内部的多个 WAR 文件可具有不同 Swagger 2.0 文档。
显示 Web 模块文档的最简单方法是,将 swagger.json 或 swagger.yaml 文件包括在相应的 META-INF 文件夹中。部署应用程序期间,API 发现功能部件会针对每个 Web 模块查找 META-INF/swagger.json 值。如果找不到 META-INF/swagger.json 值,那么 API 发现功能部件将查找 META ‐INF/swagger.yaml 值。
另一种显示 Web 模块的 REST API 文档的方法是,在 server.xml 配置文件中进行。将每个 Web 模块的 webModuleDoc 元素放置在父 apiDiscovery 元素中。例如:
<apiDiscovery> <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" /> <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" /> 例如,For example, setting the following configuration in the server.xml makes the public REST API documentation available with GET http://host:http_port/myAPI/docs and http://host:http_port/myAPI/explorer:</apiDiscovery>
webModuleDoc 元素必须具有 contextRoot 属性,以唯一地标识您要显示其文档的 Web 模块。
可选属性 enabled 用于对 Web 模块开启和关闭 API 发现。此属性的缺省值为 true。
docURL 属性指定用于查找 Web 模块文档的位置。docURL 值可以正斜杠 (/) 开头,以使 URL 相对于上下文根;例如,/30ExampleServletInEar/swagger.json。docURL 值也可以 http 或 https 开头,以表示用于标识文档完整位置的绝对 URL。
如果 Web 应用程序未提供 swagger.json 或 swagger.yaml 文件,并且应用程序包含 JAX-RS 注释资源,那么可以自动生成 Swagger 文档。服务器配置必须具有 apiDiscovery-1.0 功能部件及 jaxrs-1.1 或 jaxrs-2.0 功能部件;例如:
产品将扫描 Web 应用程序中的所有类以查找 JAX-RS 和 Swagger 注释(搜索带有 @Path、@Api 和 @SwaggerDefinition 注释的类)。产品还将在 Web 应用程序部署或启动期间自动生成相应的 Swagger 文档。<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.1</feature> </featureManager>
还可以使用 apiDiscovery-1.0 功能部件将先前生成的文档与注释扫描期间找到的文档进行合并。产品在 Web 模块中搜索 META-INF/stub/swagger.json 或 META-INF/stub/swagger.yaml 文件。如果功能部件找到这两个文件其中的任何一个,那么它将生成包含该文件内容以及 Web 模块中所有 JAX-RS 和 Swagger 注释的 Swagger 文档。可以使用此功能部件来记录非 JAX-RS servlet,因为该文档将自动与 JAX-RS 部分合并。
还可以使用此方法来绕过注释局限性,例如,显示的安全性定义。例如,META-INF/stub 中的以下 swagger.json 允许注释引用这些定义:
{ "swagger" : "2.0", "securityDefinitions" : { "petstore_auth" : { "type" : "oauth2", "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog," "flow" : "implicit", "scopes" : { "write_pets" : "modify pets in your account", "read_pets" : "read your pets" } }, "api_key" : { "type" : "apiKey", "name" : "api_key", "in" : "header" } } }
- 使用 SPI
com.ibm.wsspi.rest.api.discovery.APIProvider 接口的 getDocumentation 方法。
- 发现 API 文档。
配置 API 文档的位置后,可通过以下方式发现该文档:
- 使用 GET
https://host:https_port/ibm/api/docs 端点。
此端点提供有效 Swagger 2.0 文档,其所有可用 Liberty REST API 已合并至单个文档。对于要通过程序浏览可用 API 集的使用者应用程序(例如,API 管理解决方案),这很有用。包含带有 application/yaml 值的可选 Accept 头可以提供 YAML 格式的 Swagger 2.0 文档。此端点有一个名为 root 的可选多基数查询参数,此参数可用于过滤所发现的上下文根。例如,对 GET https://host:https_port/ibm/api/docs?root=/myApp 的调用将检索仅具有 myApp 上下文根的文档的 Swagger 2.0 文档。
- 使用 GET
https://host:https_port/ibm/api/explorer
端点。
此端点提供富吸引力的已渲染 HTTP 页面来显示 /ibm/api/docs URL 中的内容。此页面遵循标准在线样本 (http://petstore.swagger.io/) 的模式,所以用户可启动 REST API。此端点帮助您探查 Liberty 服务器上的可用 REST API,并且可能会从页面启动这些 API。
页面上的过滤器输入框允许使用上下文根的逗号分隔列表来过滤内容。
- 对于集合体控制器,请使用 GET https://host:https_port/ibm/api/collective/docs
端点。
集合体控制器上的此端点提供有效 Swagger 2.0 文档,集合体控制器及其启用了 apiDiscovery-1.0 功能部件的成员中的可用 REST API 已合并至单个文档。对于要通过程序浏览可用 API 集的使用者应用程序(例如,API 管理解决方案),这很有用。包含带有 application/yaml 值的可选 Accept 头可以提供 YAML 格式的 Swagger 2.0 文档。
此端点具有一个多基数可选查询参数(名为 root)。
查询参数 root 可过滤所发现上下文根。例如,对 GET https://host:https_port/ibm/api/collective/docs?root=/myApp 的调用将检索仅具有 myApp 上下文根的文档的 Swagger 2.0 文档。
针对 17.0.0.1 之前的版本,此端点具有两个多基数可选查询参数,它们分别名为 root和 serverID。查询参数 root 不会更改。查询参数 serverID 可过滤 Liberty 服务器中的可用 REST API。serverID 的格式为 hostName、userDir 和 serverName。例如,对 GET https://host:https_port/ibm/api/collective/docs?serverID=samplehost.com:8020,/users/admin/wlp/usr,server1 的调用将检索 Swagger 2.0 文档,该文档仅包含具有指定 serverID 的 Liberty 服务器中的可用 REST API 的文档。
- 对于集合体控制器,请使用 GET https://host:https_port/ibm/api/collective/explorer
端点。
集合体控制器上的此端点提供富吸引力的已渲染 HTTP 页面来显示 /ibm/api/collective/docs URL 中的内容。此端点帮助您探查整个集合体上的可用 REST API,并且可能会从页面启动这些 API。页面上的过滤器输入框允许使用上下文根和服务器标识的逗号分隔列表来过滤内容。服务器标识的格式为 "hostName,userDir,serverName"。必须为服务器标识添加引号 (")。要使用尝试按钮测试 API,必须在成员服务器的 server.xml 中设置跨源请求共享 (CORS)。
针对 17.0.0.1 之前的版本,在提供 API /IBMJMXConnectorREST/mbeanCount 的成员服务器的 server.xml 中,需要诸如以下示例的片段。
<cors domain="/IBMJMXConnectorREST/mbeanCount" allowedOrigins="https://controller_hostname:https_port" allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS" allowedHeaders="Content-Type,api_key,Authorization" allowCredentials="true" />
有关设置 CORS 的信息,请参阅在 Liberty 服务器上配置跨源资源共享。
注: CORS 需求仅适用于 Swagger UI 的集合体版本 (https://host:https_port/ibm/api/collective/explorer)。 使用其他端点来显示公用 REST 文档。
与先前提及的端点不同,访问这些端点不需要密钥库服务对象条目,也不需要用户注册表设置。但是,可以设置密钥库服务对象条目以通过 HTTPS 访问端点。
缺省情况下,为集合体控制器提供了四个端点:- GET http://host:http_port/api/docs
- GET http://host:http_port/api/explorer
- GET http://host:http_port/api/collective/docs
- GET http://host:http_port/api/collective/explorer
缺省情况下,为服务器提供了两个端点:- GET http://host:http_port/api/docs
- GET http://host:http_port/api/explorer
您可以在 server.xml 文件中更改具有 publicURL 属性的公共端点的 URL。例如,在 server.xml 中设置以下配置可使公共 RESTAPI 文档可用于 GET http://host:http_port/myAPI/docs 和 http://host:http_port/myAPI/explorer:
<apiDiscovery publicURL="myAPI" />
缺省情况下,会在公共 REST API 文档中显示已部署 Web 应用程序添加的所有 REST API 端点,但是不包含诸如 JMX REST 连接器 REST API 的内部服务器端点。您可以针对 Web 模块设置 public="false" 属性,以便不显示该模块所显示的 REST API。例如,将以下配置添加到 server.xml 会导致 Web 模块不会在公共 REST API 文档中显示 REST API。
<apiDiscovery publicURL="myAPI"> <webModuleDoc contextRoot="/22ExampleServlet" public="false" /> </apiDiscovery>
使用 server.xml 文件中的 swaggerDefinition 属性,覆盖 /docs 端点提供的 Swagger 2.0 文档中一些字段。
您可以使用 swaggerDefinition 指定包含要覆盖的字段的 JSON 或 YAML Swagger 片段。可以覆盖 info、schemes、consumes、produces 和 externalDocs 字段。
对于集合体控制器,使用集合体服务查询列出整个集合体中所有可用的公共 RESTful API(服务)。
启用 apiDiscovery-1.0 功能部件后,ObjectName 值为 WebSphere:feature=apiDiscovery,name=APIDiscovery 的管理 bean (MBean) 在 Liberty MBeanServer 中注册。此 MBean 提供以下属性:
- DocumentationURL 属性是 /ibm/api/docs 端点的完整 URL,它显示原始 JSON 或 YAML 文档。
- ExplorerURL 属性是 /ibm/api/explorer 端点的完整 URL,它显示文档的呈现 UI。
可以使用此 MBean 来了解 REST API 发现是否已启用以及客户机可以在何处访问该功能部件。
- 使用 GET
https://host:https_port/ibm/api/docs 端点。
示例
您可以在 OpenAPI 接口中以及 WASdev Web 站点上找到有关“REST API 发现”的更多信息。
观看:IBM MediaCenter 上的 IBM WebSphere Application Server Liberty API 发现视频提供了演示视频的示例和链接。(V8.5.5.9)
子主题
覆盖 Swagger 2.0 文档字段
使用 server.xml 文件中的 swaggerDefinition 属性,覆盖 /docs 和 /explorer 端点提供的 Swagger 2.0 文档中一些字段。列出集合体中所有公共 RESTful API
使用集合体服务查询,发现有关整个集合体中所有公共 RESTful API(服务)的 API 文档。此查询以列表格式提供文档。- 预订 Liberty REST API 更新
Liberty REST API 发现功能部件现在展示新 REST API(即 /ibm/api/docs/subscription),它允许用户预订任何 REST API 更新,例如,可用的新 API 或要移除的旧 API。要在端点中有特定 Liberty 实例提供的任何更改时立即通知用户,这会很有用。 - 在集合体中预订 Liberty REST API 更新
在集合体控制器中使用预订 API 以即时了解有关新 REST API、已移除 API 或对 API 的更改(例如,特定集合体成员服务器内的端点中的更改)的信息。 - 用于将 API 推送到 IBM API Connect 中的 REST 端点
REST 端点对于本地和云 Liberty 用户而言位于中央位置,可以使用此端点对 API 进行可视化、调用以及将其推送到 IBM® API Connect 中。

文件名:twlp_api_discovery.html